Skip to content

Latest commit

 

History

History
207 lines (163 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

207 lines (163 loc) · 10.1 KB
Raw

Bug Reporting 🐛

One of the most important things you can do is report bugs. Please reference how to report a bug and follow the issue templates when adding new bugs.

Development

  • Most work happens in sub modules. These are found in the packages directory 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

We have lots of tooling dedicated to ensuring consistent code. We use Prettier, Typescript, and ESLint to help us deliver quality code. These are checked by the build system and should be enforced at commit time by Husky.

Some of the modules are written in Typescript, others are still plain Javascript. In the javascript modules and any dependencies we include, it is important to only write ES5 code. This ensures good browser compatability for Turf users, and is checked at build time.

Making sure that the monorepo packages can be managed at scale, we use Monorepolint which allows us to programatically manage the various files in each package.

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…
  • index.ts - If you prefer to write Typescript instead of Javascript, use this instead of index.js and index.d.ts.
  • 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 tests the custom TypeScript types declared 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

Prerelease

  • create a new branch with some name
  • write up changelog changes (manually), commit that
  • yarn lerna version --no-push --no-commit-hooks 6.2.0-alpha.2 This lets lerna update the package.json versions (and dependencies) and commits the result as well as adds a tag --no-push because we can't push to master --no-commit-hooks because otherwise the commit hooks will prevent the commit
  • git push origin --follow-tags $branch
  • make PR
  • merge PR
  • re-fetch the new master and check it out locally
  • yarn install
  • yarn lerna publish --dist-tag prerelease --ignore-scripts from-package
    • --dist-tag is important to avoid tagging this release as the stable release
    • --ignore-scripts skips the build steps since they already ran during yarn install
    • you will likely need to publish several times as your OTP expires
    • you might get rate limited as well
    • between publish attempts, you'll have to undo the gitHead changes in the package.json files

Release

  • create new branch with some name
  • write up changelog changes (manually), commit that
  • make PR (don't merge)
  • yarn lerna version --no-push --no-commit-hooks 6.2.0
  • git push origin --follow-tags $branch
  • merge PR
  • re-fetch the new master and check it out locally
  • yarn install
  • yarn lerna publish --ignore-scripts from-package

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
....

Public website

turfjs.org is managed in a separate repo with its own contributing guide.

Other Dependencies

  • Turf uses Yarn and lerna during the testing, packaging and publishing process.
    • Lerna will be automatically installed when you run npm install in the root directory.
    • Yarn will need to be installed on your computer, installers are available via the yarn website.

Financial contributions

We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.

Credits

Contributors

Thank you to all the people who have already contributed to turf!

Backers

Thank you to all our backers! [Become a backer]

Sponsors

Thank you to all our sponsors! (please ask your company to also support this open source project by becoming a sponsor)