Release Procedure
The release process involves a couple changes to the repository: updating the version number in package.json and adding a changelog. In order to make these release-related changes, create a branch in your repository clone. Note that all the examples below use ${R1} as the release version, ${R0} as the previous release, and ${R2} as the next release. You'll want to use the appropriate version numbers for the release you're working toward.
Set the R0, R1, and R2 variables. For example:
R0=6.10.0 # previous release
R1=6.11.0 # this release
R2=6.11.1 # next release
Check out a new release branch:
git fetch openlayers
git checkout -b release-v${R1} openlayers/main
Create a changelog for all merges to main since the previous release. You'll want to create a log for all changes since the previous release and name the resulting file like the target release.
echo "# ${R1}\n\n#### List of all changes\n\nSee below for a complete list of features and fixes.\n" > changelog/v${R1}.md
./tasks/changelog.sh v${R0}.. >> changelog/v${R1}.md
Edit the resulting changelog file with any summary notes or special upgrade considerations.
You can extract the upgrade considerations from the changelog/upgrade-notes.md file, by looking at any upgrade notes since the previous release.
If the changelog/upgrade-notes.md
file does not already have a header for the current release, create a header with the version number.
Update the version numbers in package.json to reflect the target release.
# mac flavor sed
sed -i '' "s/\"version\": \".*\"/\"version\": \"${R1}\"/" package.json
To pick this change up in package-lock.json, run
npm install
Commit the version update and new changelog:
git add package.json package-lock.json changelog
git commit -m "Updates for the ${R1} release"
Create a pull request for the release branch. This allows for any final review of upgrade notes or other parts of the changelog. Do not merge yet!
git push openlayers release-v${R1}
After CI jobs for the above pull request pass, tag the release:
# tag the latest from openlayers/release-v${R1}
git tag -a v${R1} -m "${R1}"
# push the tag
git push openlayers v${R1}
Pushing the tag will trigger a number of actions that create the GitHub release, publish the ol package to the npm registry, and update the https://openlayers.org website. Visit the actions page and wait for the Create Release, Publish Package, and Deploy Website jobs to finish.
The Create Release job creates the GitHub release in draft mode. Edit the release to update the notes, copying from the changelog created in the previous step.
The Publish Package job builds the ol package and publishes it to npm. Confirm that the package is published as expected.
The Deploy Website job pushes a commit to the openlayers.github.io repository that triggers a deploy of the GitHub Pages website. This can take 15 minutes or so. Confirm that the website looks good after the Deploy job for the openlayers.github.io repository finishes.
This is to allow users to update to ol@dev seamlessly. Check out the release branch again:
git checkout release-v${R1}
Edit package.json and bump the patch version number, e.g.
# mac flavor sed
sed -i '' "s/\"version\": \"${R1}\"/\"version\": \"${R2}-dev\"/" package.json
Propagate this change to package-lock.json:
npm install
Commit and push this change:
git add package.json package-lock.json
git commit -m "Develop on ${R2}-dev"
git push openlayers release-v${R1}
Give the pull request for the release branch a final review, and merge it into main.
Move all open issues that are in the current milestone to the next one if needed. Close out the milestone and create a milestone for the next release.
Tweet with the openlayers account, something like:
OpenLayers v${R1} is out! Thanks to everyone who contributed. https://github.com/openlayers/openlayers/releases/tag/v${R1}
For a patch release, the process is basically the same as for a minor release. The significant difference is that you want to create a new branch from the minor tag. For example:
git fetch --tags --prune openlayers
git checkout -b release-v3.20.1 v3.20.0
Next, you want to cherry pick commits that fix regressions in the minor release.
# for each bug fix commit
git cherry-pick <SHA_OF_BUG_FIX_COMMIT>
Since the changelog.sh relies on merge commits, and there won't be any merge commits between the previous release tag and your patch release branch, you'll need to manually create the changelog. Copy one of the existing changelogs for a patch release as a starting point. Link to the pull requests that included the original commits that you cherry picked above.
From this point, you can follow the normal release process (after the changelog step).