Skip to content

Latest commit

 

History

History
337 lines (259 loc) · 18.3 KB

CONTRIBUTING.md

File metadata and controls

337 lines (259 loc) · 18.3 KB
Raw

Getting Started

One of the most important things you can do is report bugs. Please reference how to report a bug and when opening an issue, follow the template.

To propose an enhancement for Turf, open an issue, or start a discussion.

To make a code contribution, follow the steps for how to contribute.

Architecture

  • GeoJSON is the lingua franca of Turf. It should be used as the data structure for anything that can be represented as geography.
  • Most work happens in sub modules. These are found in the packages directory prefixed with "turf-".
  • Turf modules are small, containing a single exported function. This function is exported from a top-level index file.
  • Many turf modules depend on other smaller Turf modules.

How to contribute

If you don't have write access to the Turf repository (most will not), you will need to follow the Github guidelines and fork the Turf repo to your own account, create a feature branch, and open a Pull Request back to the main Turf repo.

If you do have write access to the Turf repo (core contributor), you can clone it locally. This is required for doing a release. You can also push feature branches directly to the Turf repo and open PR's against them. Consider prefixing your feature branch names with your initials (for example tw/my-feature).

If you'd like to become a core contributor, just start making contributions, and inquire.

Local Setup

Once you've cloned a Turf repository, and have a terminal open and currenty in the top-level turf directory. Run the following:

  • git checkout master (if not already)
  • corepack enable pnpm
    • enable pnpm as a package manager. Requires Node 16+. Alternatively just npm install -g pnpm.
  • pnpm install
    • install dependencies and build modules
  • pnpm test
    • run all tests and linters

You're now ready to contribute.

Structure of a Turf module

Turf modules are under the packages directory. For example packages/turf-area. Here's how they are structured.

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 pnpm 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. pnpm install looks to this file to install dependencies in ./node_modules.
  • README.md - This README is generated automatically by running pnpm 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.
Development tips
Work in a feature branch when possible - `git checkout -b my-feature` - Create it right away off of master. - This allows you to keep your local master branch clean and in sync with the official remote, for creating new branches at any time.

As you make code changes

  • Run npm test from any submodule to make sure tests keep passing as you go. (for example cd packages/turf-area and npm test)
  • Occasionally Run npm test at the top-level directory to run test for all modules.
    • This will ensure that you haven't introduced errors affecting other turf modules.
Cleaning up
To reset your current branch, throwing away any partial and uncommitted work - `git reset --hard`

Merging branches, deleting branches and other management tasks are left for you to work out on your own.

Staying up to date
To update your local master branch with the latest code for all branches from the Github remote `origin`. - `git fetch remote`

Preparing a pull request

A simple, complete pull request is more likely to get merged.

But I don't know how
If you don't know how to make a solid PR, just submit a draft PR, and ask for feedback. Then improve it and re-ask for feedback until it's ready.

Pull Request Checklist

  • Briefly summarize the need and solution. Link to the issue it's resolving if exists.
  • Add tests. Even for bug fixes. Just a simple test case that reproduces the issue and demonstrates it's fixed.
  • Update JSDoc comments if the function signature changes or docs need improvement (See for example packages/turf-area/index.ts)
  • Run a full npm test at root level, confirming no cross-module issues. If you don't catch this now, the Github CI will.

Guidelines

  • Feel free to ask if a feature/enhancement is needed/wanted before doing the work.
  • Keep pull requests small and focused.
  • Avoid large dependencies at all costs.
  • Make sure that your code can run in the browser (ie: don't make calls to external services, don't hit the filesystem, etc.).

Doc generation

Know that module README.md files and https://turfjs.org API docs are auto-generated from JSDoc comments.

  • As a contributor, all you need to do is update the JSDoc comments.
  • For example if you change a top-level Turf functions signature (params, return type) or just want to improve the docs.
  • JSDoc comments are found in the top-level index file for each module (for example turf/packages/turf-area/index.ts). For example look for @name, @params, @returns, @example.

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.

  • Linters are run at commit time, using a pre-commit hook in .husky/pre-commit. See the package.json lint:staged section.

Publishing

Prerelease

A prerelease action is available that publishes a canary release for every commit or PR merged to the master branch. However, this action is only enabled when needed.

When used, it publishes an alpha release to NPM (e.g. 7.0.0-alpha.116 where 116 is the number of commits to master since the last release tag).

  • The version number is calculated by a combination of the output of git describe and the publish:prerelease script in the root package.json. It is typically setup to do a minor prerelease, but can be changed, such as prior to a major release.

Release

A turf release is initiated from your local computer, and then built and published remotely via a github actions.

To make a release as a core contributor, you will need:

  • Turf repository write permission

  • Turf npm organization publish permission

  • A clean local copy of the Turf Github repository (not a fork!). Starting with a fresh clone will ensure it's clean.

    • Depending on your auth method
      • git clone [email protected]:Turfjs/turf.git turf-release
      • or git clone https://github.com/Turfjs/turf.git turf-release
    • cd turf-release - start at the top-level of the repo
    • pnpm install
    • pnpm test - make sure everything is passing

  • If you choose to clean up an existing copy instead, be very careful:

    • git remote -v - verify your remote origin points to https://github.com/Turfjs/turf.git
    • git checkout master
    • git reset --hard - reset your local working copy, will lose any uncommitted or unstashed work!
    • git fetch origin - fetch latest commits
    • git rev-list master...origin/master - verify local master in sync with remote, command output should be empty
    • pnpm install
    • pnpm test - make sure everything is passing

Before release:

  • If necessary, make and merge a PR with any last minute housekeeping items.
  • Turf's documentation (README.md files) should already be up to date as it is generated automatically on commit from JSDoc comments in source files.
  • Review PR's and decide the new version number to be published. See semantic versioning.

Run the following release commands, replacing 7.0.0 with your version number:

  • create a release branch and switch to it. All building, tagging and publishing will be done on the release branch, and then merged back into master in a later step.

    • git checkout origin/master -b release-7.0.0

  • increment the version number of all packages, and create a local commit, without pushing to origin. This will also create a release tag.

    • pnpm lerna version --no-commit-hooks --no-push 7.0.0

  • Push the release branch and the release tag.

    • git push origin release-7.0.0 --follow-tags
    • Pushing the tag will trigger the Github release action which you can view the status of at - https://github.com/Turfjs/turf/actions. If successful, a new version of all turf packages will have been published on NPM.

  • If the release action was not successful

    • commit any changes to master to fix it.
      • Make a prerelease if helpful to make sure the release action is successful.
    • Then reset by deleting your tag and branch locally and remotely.
      • git push --delete origin v7.1.0
      • git tag --delete v7.1.0
      • git push -d origin release-7.0.0
      • git branch -d release-7.0.0
    • Now redo the steps above starting with creating "A clean local copy of the Turf Github repository"

  • If the release action was successful, now create a Pull Request for the release to merge back to master.

    • You may be given a link in the output of the branch/tag push command to create the PR.
    • If you don't get this message, just go to https://github.com/Turfjs/turf/pulls and you should be prompted at the top to create a PR for this new branch you just pushed.
    • If that prompt doesn't appear, then just create a new pull request from the PR page and make sure the title is the version number e.g. v7.0.0 and that it is merging your release branch -> to master.
    • Here is an example PR - Turfjs#2615.
    • Get approval for the release PR, then "Squash and merge" it.
      • Do not delete this branch in Github after merging, the release tag points to it. If you do, click "Restore branch" at the bottom of the merged PR.

Follow-on steps

  • As part of the release action, a draft Github release will have been created at https://github.com/Turfjs/turf/releases with an auto-generated changelog.
    • Edit and add to the release notes for readability and completeness, specifically noting any breaking changes. Use past releases as a guide.
    • Be sure to "Save draft" each time, then ask for a review or edits from other contributors.
    • Try not to leave the notes unpublished more than a day, people rely on these notes for upgrading.
    • Once ready, click Publish release. This will make the release notes publicly accessible and notify all watchers of the project.
    • You can edit and republish your release notes after this, but that will likely notify followers, so best to get it right the first time.
  • Release a new version of the API docs for the https://turfjs.org website.

Documentation

  • API docs for each turf package are extracted from JSDoc comments in the source code into the top-level README.md files. README's are automatically updated on commit using via the pre-commit hook.

Should you want to generate new README files manually, use pnpm run docs:

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

Documentation - Examples

Only build docs for @turf/center

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

> @turf/[email protected] docs /Users/mac/Github/turf/packages/turf-center
> node ../../scripts/generate-readmes

Building Docs: @turf/center

Builds docs for all modules

$ cd ./turf
$ pnpm run docs
> @ docs /Users/mac/Github/turf
> tsx ./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

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

Other Dependencies

  • Turf uses pnpm 8 and lerna during the testing, packaging and publishing process.
    • Lerna will be automatically installed when you run pnpm install in the root directory.
    • Pnpm will need to be installed on your computer, installers are available via the pnpm website. When using corepack, this is automatically installed when running pnpm.

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)