Create a release branch
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
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 package.json
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"
Pull request
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}
Tag
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}
Publish to npm
Run the publish.sh task with the version number as specified in the package.json (without the "v" prefix). The publish.sh script makes sure that the tag name and the version in package.json for that tag match. This implies you have an npm user account which has the correct permissions.
./tasks/publish.sh ${R1}
Bump the patch version number
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/${R1}/${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"
Merge the release branch
Push the pending changes to the release branch
git push openlayers release-v${R1}
Give the pull request for the release branch a final review, and merge it into main.
Update website
You need a local clone of the openlayers.github.io repo, with the build branch checked out.
First of all make sure your build branch is up to date. Note that the deploy step requires that the remote is named origin.
git checkout build
git fetch origin
git reset --hard origin/build
Edit the package.json page to include the version number for the latest release.
# mac flavor sed
sed -i '' "s/${R0}/${R1}/" package.json
Update package-lock.json and dependencies.
npm install
Commit and push the change:
# commit the change
git add package.json package-lock.json
git commit -m "Updates for v${R1}"
# push to GitHub
git push origin build
Publish the release artifacts (examples and source) on the website. In a working copy of the openlayers/openlayers.github.io:
# publish
treeish=latest npm run deploy
(Note that the latest alias above will deploy the version specified in package.json.)
If you run into Warning: ENFILE: file table overflow check out this Stack Overflow post (or try sudo launchctl limit maxfiles 2048 unlimited).
Create release page and post archive for download
Create an archive from the artifacts created by the npm run deploy step above. This includes the documentation and source.
treeish=latest npm run zip
Note: we do not rely on the archive created by GitHub because it only contains the source code. Our archive includes the ol builds, the hosted examples, the generated API docs, etc.
Draft a new release with the latest tag. Edit the GitHub release page for the tag to include the Markdown from the changelog created above.
Attach the .zip archive created above to the release page.
Github issues
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}
Patch releases
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 remote update
git checkout -b v3.20.1 origin/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).