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 --force-publish --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
lerna info Assuming all packages changed

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

Confirm four 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.
4. lerna assumes all packages have changed, so will keep version numbers in sync across all of Turf.

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 and publish step.

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 there was a problem - no need to panic - see Failed Publish below for what to do next.

If the release action was successful, you now need to merge the release branch back to master. Note that this MUST be a vanilla merge of the PR - Merge pull request. Do not Squash and merge as this will leave the release tag "isolated" out on the unmerged release branch, and lerna won't be able to see it during the next release cycle.

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

Failed Publish

If the build or publish action was not successful, you will first need to roll back any release artefacts so far. That includes any tags or branches you created locally, and anything pushed to the remote. Remember that you're working in the Turf repo proper (not a fork) so proceed gently, making sure you understand what each step is doing.

Btw,checkout master again so you'll be able to delete your release branch locally.

git checkout master
git push --delete origin v7.1.0
git tag --delete v7.1.0
git push -d origin releases/7.1.0
git branch -d releases/7.1.0

Once that's done and the Turfjs/turf repo is restored to where it was before you started, time to figure out what went wrong. Any fixes should take place via a normal PR, including reviews. Then recommence the release process from "Clone a fresh local copy of the Turfjs/turf Github repository", ideally blowing away your local clone and starting afresh.

Sometimes it helps to make a prerelease if helpful to make sure the release action is successful.