Publishing instructions revision draft

Publishing

Before starting

Before commencing the release process, in your forked repo make and merge a PR like you normally would with any last minute housekeeping tasks. For example, confirm Turf's automatically generated README.md files are up to date with a pnpm run docs from the project root. Run pnpm test from the project root to make sure all tests are passing and code has been linted.

Once the release process is started, we want to limit changes to the repository to versioning only. No last minute code tweaks or doc tidy ups!

Don't worry about changing the Turf package versions in package.json files. lerna will do that for us below.

Review PRs merged since the last release and decide what semver bump is required - patch, minor, or major. See semantic versioning.

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

Clone a fresh local copy of the Turfjs/turf Github repository. Starting with a fresh clone will eliminate the chance of any local cruft corrupting the release.

You mustn't use a fork! This has to be a clone of the turfjs/turf repo. Otherwise tags (essential for lerna to work) won't be visible.

git clone [email protected]:Turfjs/turf.git turf-release
cd turf-release/
pnpm install --frozen-lockfile

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

git checkout master -b releases/7.1.1
git push origin releases/7.1.1

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

Replace patch with the semver bump you want to make.

pnpm lerna version patch --include-merged-tags --no-commit-hooks --no-push

Make sure to read the summary of what lerna is about to do before confirming.

lerna notice cli v8.1.7
lerna info current version 7.1.0
lerna info Looking for changed packages since v7.1.0

Changes:
 - @turf/turf: 7.1.0 => 7.1.1
 ...

Confirm three things before proceeding:

1. The current version is what you expected. This should almost always be the version currently published on NPM.
2. The changed packages since version is what you'd expect. Again, this should be the version currently published on NPM.
3. The new version that lerna is going to bump each package to is what you expected.

If not, this could point to a problem with previous release tags, or some other issue. Discuss with the other maintainers before proceeding.

You should now see a single new commit and v7.1.1 tag on the release branch in your local repo. The changes committed should consist only of version alterations to lerna.json and package-lock.json in the project root, and package.json in each of the individual packages.

Now it is time to prompt the remote build and release process via github actions.

We do this by pushing the release tag and branch to the remote repository. It's the appearance of the vX.X.X tag on the remote that triggers the build.

git push origin releases/7.1.1 --follow-tags

All going well, you will see a release action started in github actions.

Once that is completed, again all going well, you will see your new version of Turf available 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, you now need to merge the release branch back to master. This will allow lerna to find that release tag next time we want to publish.

Create a PR to merge from releases/7.1.1 back to master. There shouldn't be any conflicts as hopefully(!) no one has been merging PRs since you started doing the release at the top of this page.

Importantly, when squashing and merging the PR do not delete the release branch. This is where the version tag v7.1.1 will live forevermore.

That's the release tagged, published, and merged. Congratulations! 🎉 Time for the documentation.

Release Notes

As part of the release Github 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 or major bug fixes. Use past releases as a guide. Keep the release in draft status until other contributors have had a chance to review.

As people rely on these notes for upgrading though, try to expedite getting them finalised. Ideally not more than a day.

Once ready, click Publish release to make the release notes publicly accessible and notify all watchers of the project.

Website Documentation

Release a new version of the API docs for the https://turfjs.org website.

Prereleases

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.