This document is for maintainers. This is the set of steps for releasing a new version of BEF.
We follow SemVer. Determine what type of release this must be (major, minor, patch) given the changes that are in master. That will dictate what version number to use for the new release.
The version is set in a number of files, both for Maven and for OSGi (Eclipse). For Maven pom.xml files, keep the SNAPSHOT suffix (e.g. 1.3.1-SNAPSHOT). For OSGi meta files, keep the qualifier suffix (e.g. 1.3.1.qualifier).
Tycho has commands for this, and is a good start, but they don't do the full job:
mvn -X -DnewVersion=1.3.1-SNAPSHOT tycho-versions:set-version
mvn -X tycho-versions:update-eclipse-metadata
In the end, you will need to manually ensure the new version is applied everywhere. This PR for version 1.3.1 gives you an idea. Grepping through the code base looking for the old versions is not a bad idea.
Verify all the files are in order before submitting to master with this command:
mvn clean verify
Prior to releasing BEF, please test it from a fresh install of standard Eclipse (not an SDK version). Launching BEF (as inner eclipse) from the Eclipse SDK (outer eclipse) is not a sufficient test. Certain packaging problems will not appear when launched from Eclipse SDK. Instead, please download the latest JEE Eclipse to test with.
The build will write the built feature into the releng/p2repository/target/ directory. You can install from the archive zip in that location. Use the standard Eclipse Help -> Install New Software... menu and choose to Add an Archive.
Make sure to run through an import of a decently complex Bazel workspace. Things to look for:
- The Bazel Classpath is correct for each project
- There are no build errors in the Problems View
- Open a .java file in an editor an make sure there aren't any red squigglies
Our update site is the official location of our releases.
🔥 The update site is our live installation location for our users. If you are doing experimental work with the release process, please do not release directly to gh-pages branch. Update the github-pages-deploy-action stage in the workflow to deploy to a test branch if you have any doubts about what you are releasing. Also, be prepared to rollback the gh-pages branch at the first sign of trouble (see steps on how to do this in next section).
Our GitHub repo has our release process implemented as a GitHub Actions workflow. To build the release, make sure you have your versions set and committed to master (see above).
Then, run the release workflow:
- Navigate to the Bazel Eclipse Actions tab in GitHub
- Click on the Bazel Eclipse Feature Release button in the left nav
- Click on the Run Workflow button on the right side, and pick the branch to release from (normally master)
- Monitor the build, it should take about a minute
- Navigate to the gh-pages branch of the repo. It contains all the files from the release.
- Verify the files look to be correct (i.e. check version in the filenames)
First, check that our landing page is available and has correct instructions:
Next, follow the instructions on the page and install BEF into a fresh copy of Eclipse. Finally, repeat the install test with the zip file that is in the root directory of the gh-pages branch
If anything fails, revert the changes in the gh-pages branch ASAP! It is the live update site for all of our users.
# assume release 1.3.2 has a problem, revert gh-pages back to 1.3.1
git checkout gh-pages
git reset --hard 1.3.1.updatesite
git push --force origin gh-pages
After the release build has been confirmed, please create a new release in our Releases list. Click the Draft a new release button to get started.
Please follow the pattern of previous releases. Be sure to list the changes and give credit to outside contributors. Especially look at the naming convention of the archive file, as in bazel-eclipse-feature-1.3.1-release.zip.
As part of the release, you will create a tag. Follow our convention of using the bare SemVer, like 1.3.1.
In the previous step, you tagged the master branch as a side effect of creating the release record. We also want to tag the update site, as we may need to rollback if the next release fails. This is done by tagging the gh-pages branch.
git checkout gh-pages
git pull
git tag 1.3.1.updatesite
git push origin 1.3.1.updatesite
For each release, we need to add an entry to our Marketplace record. The BEF record is here, which will have an Edit button if you are entitled:
The release workflow is defined using GitHub Actions. Instead of explaining how it works, here are some pointers to some interesting files: