Skip to content

Latest commit

 

History

History
140 lines (115 loc) · 5.14 KB

CONTRIBUTING.md

File metadata and controls

140 lines (115 loc) · 5.14 KB
Raw

🐛 How to report a bug

How To Contribute

  • Most work happens in sub modules. These are modules prefixed with "turf-".
  • If you would like to propose a new feature, open an issue in Turfjs/turf.
  • Always include tests. We use tape.
  • Turf modules are small, containing a single exported function.
  • GeoJSON is the lingua franca of Turf. It should be used as the data structure for anything that can be represented as geography.
  • Avoid large dependencies at all costs.
  • Turf is used in a wide range of places. Make sure that your code can run in the browser (ie: don't make calls to external services, don't hit the filesystem, etc.).
  • The README.md files in packages/turf-<module> are automatically generated from the JSDocs of the index.js. Please modify the JSDocs instead of modifying the README.md files directly. Then update/create the README.md executing ./scripts/generate-readmes or runing npm run docs from the root TurfJS directory.
  • Finally run npm test from the project root folder to run all the tests required for deploying the project.

Code Style

To ensure code style, at the turf root level run

$ npm run lint

Structure of a turf module

turf-<MODULE NAME>
│   index.js
│   index.d.ts
│   bench.js
│   test.js
│   types.ts
│   package.json
│   README.md
│   LICENSE
│
└───test
    │
    ├───in
    │   points.geojson
    │
    └───out
        points.geojson

To get started with a new module navigate to the root directory and run

$ node ./scripts/create-new-module <MODULE NAME>

it will create a new folder inside packages with a simple boilerplate for your module.

  • index.js - This file contains, in order, the various modules you need to import, the JSDocs documentation, and, finally, the single exported function that the module provides. For more on the types supported in the documentation, see…
  • index.d.ts - This is a TypeScript file that describes your function’s signature. For more on the types supported in TypeScript, see…
  • bench.js - This file uses Benchmark to time your function.
  • test.js - This file includes your tape tests. We prefer dynamic testing built from GeoJSON files placed in ./test/in that are subsequently written to ./test/out if your REGEN environment variable is set to true. If REGEN is set to a different value, then running npm t will compare the output of the tests to the files already present in ./test/out.
  • types.ts - A file that lists the custom TypeScript types used in index.d.ts.
  • package.json - The node metadata container file. Modules imported in index.js should be listed here under dependencies, and modules used in test.js and/or bench.js should be listed under devDependencies. npm install looks to this file to install dependencies in ./node_modules.
  • README.md - This README is generated automatically by running npm run docs from the project root level. DO NOT edit this file.
  • LICENCE - Like the README, this file should not be edited.
  • test/ - This directory holds the GeoJSON files that provide data for dynamic tests (in ./test/in) and the results of the tests (in ./test/out). The files in ./test/out should not be edited by hand. They should be generated dynamically by setting the environment variable REGEN to true, and then the tests should be checked against these files by setting REGEN to some other value. The resulting out-files can be drag-dropped into geojson.io to see, visually, if the module is behaving appropriately.

Publishing

Install lerna:

$ npm install -g lerna@2.0.0-beta.34

Publish a test release:

$ lerna publish --canary

Documentation

To update TurfJS's Documentation (README.md) use the following npm run docs:

  • inside a module: will only generate the docs of that module.
  • main folder: will generate docs for all modules.

Documentation - Examples

Only builds docs for @turf/center

$ cd ./turf/packages/turf-center
$ npm run docs

> @turf/center@5.0.4 docs /Users/mac/Github/turf/packages/turf-center
> node ../../scripts/generate-readmes

Building Docs: @turf/center

Builds docs for all modules

$ cd ./turf
$ npm run docs
> @5.0.0 docs /Users/mac/Github/turf
> node ./scripts/generate-readmes

Building Docs: @turf/along
Building Docs: @turf/area
Building Docs: @turf/bbox-clip
Building Docs: @turf/bbox-polygon
Building Docs: @turf/bbox
Building Docs: @turf/bearing
Building Docs: @turf/bezier-spline
Building Docs: @turf/boolean-clockwise
....