turf/docs/PUBLISHING.md

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 git@github.com: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 - https://github.com/Turfjs/turf/pull/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.