A PASS release produces a set of Java artifacts, and Docker images. Java artifacts are pushed to Sonatype Nexus and Maven Central repositories. Docker images are pushed to GitHub Container Registry. The PASS Docker environment is updated with references to the released images. Source code is tagged and release notes made available.
Each release of PASS has its own version which is used by every component. PASS uses MAJOR.MINOR.PATCH semantic versioning approach.
The version should be chosen based on those guidelines.
release-actions-X.X.X.md. Update the template with any new steps made during the release process.A new release for each relevant project should be created in the GitHub user interface until automation is put in place.
The release notes are generated automatically by GitHub, but references to the release artifacts should be added manually.
Most of the PASS release process is automated new, but if we need to do parts of the process manually, make sure the following software is installed:
| Name | Version |
|---|---|
| Java | 17 |
| Maven | 3.8.x |
| Docker | 20.10.x |
| Docker Compose | 2.x |
The Sonatype deployment is handled by the automations. This information is provided for doing a Java release manually.
Developers will need a Sonatype account to release Java projects. Maven must be configured to use the account by modifying your ~/.m2/settings.xml. Documentation for Sonatype publishing is available here: https://central.sonatype.org/publish/publish-guide/
Example pom setup:
<settings>
<servers>
<server>
<id>ossrh</id>
<username>YOUR_SONATYPE_USERNAME</username
<password>YOUR_SONATYPE_PASSWORD</password>
</server>
</servers>
<profiles>
<profile>
<id>ossrh</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<gpg.executable>gpg</gpg.executable>
<gpg.passphrase>YOUR_GPG_PASSPHRASE</gpg.passphrase>
</properties>
</profile>
</profiles>
</settings>
Developers will need a GitHub account which is a member of the eclipse-pass organization.
The Publish: Release All GitHub workflow will release all projects in the correct order.
However, if for some reason, a manual release is required, an order must be followed.
The Java projects must follow a strict sequence, following its dependency hierarchy. Other Javascript based projects can be released in any order. Both the Java and non-Java releases can be done in parallel, as there are no direct code dependencies between them.
mainpass-dockerThese projects have GitHub workflow automations in place to perform releases that need to be triggered manually. See more detailed release steps with automations
The release automations will follow these steps. You will only need to follow this process if the automations fail.
Maven is used to perform many of the release tasks. It sets versions and builds, tests, and pushes release artifacts. Maven may also build Docker images.
The versions of all the Java artifacts are the same for a release. The parent pom in main sets the version to be inherited by all its children. This project therefore needs to be released first, as all other projects need to reference it. After this is released, other projects are released in an order which guarantees that all PASS dependencies for them have already been released. You will need to wait for artifacts to show up in Maven Central before building a module which depends on them.
The process itself can be described as follows: release main, . For convenience, we set and export environment variables RELEASE for the release version, and NEXT for the next development version (an example might be executing export RELEASE=0.1.0 and export NEXT=0.2.0-SNAPSHOT)
For each of these child projects, we first clone the source from GitHub, and operating on the principal branch (usually main).
Update the reference to the parent pom and set the release version.
mvn versions:update-parent -DparentVersion=$RELEASE
mvn versions:set -DnewVersion=$RELEASE
After this, we do build and push the artifacts to Sonatype, commit the version change, and tag it:
mvn -ntp -P release clean deploy
git commit -am "Update version to $RELEASE"
git tag $RELEASE
Push any created images to GHCR after logging in. See [https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry] for information.
docker push IMAGE_NAME:$RELEASE
Push commits and tags to GitHub:
git push origin
git push origin --tags
Finally, the new development code needs to be pushed to built and pushed GitHub. Repeat the process above with the dev version, but do not create the tag.
At this point, we should have deployed the release to Sonatype (and eventually to Maven Central), pushed a tag to GitHub, and deployed the new development release to Sonatype.
In addition, the project may be released on GitHub. This provides a way to add release notes for a particular project. A GitHub release is done manually by uploading artifacts through the UI. The release version and tag should be the same used for Maven Central. Release notes can be automatically generated from commit messages and then customized.
See the [/.github/workflows/release.yml] for the details on the exact commands that are run.
main, pass-core, pass-supportThe following projects can be released by performing the following steps when the release needs to be performed manually.
pass-uiUpdate the version in package.json and in build.sh, and commit those changes via a PR to the pass-ui repo.
Build a new docker image from within the pass-ui repo by running:
sh build.sh ~/pass-docker/.env
Note, you might want to ensure node_modules are removed first to ensure a clean build.
Push that image to ghcr. For example: docker push ghcr.io/eclipse-pass/pass-ui:<your-version-tag-here>
pass-authUpdate the version in package.json, and commit that change via a PR to the pass-auth repo.
Build a new docker image from within the pass-auth, for example by running:
docker build --no-cache -t ghcr.io/eclipse-pass/pass-auth:<your-version-tag>
Push that image to ghcr. For example: docker push ghcr.io/eclipse-pass/pass-auth:<your-version-tag-here>
pass-acceptance-testingAll that’s required is to tag a new release in the Github UI.
After pushing the images to ghcr, update the appropriate image lines in docker-compose.yml in pass-docker with the new sha’s returned by the pushes to ghcr. Open a pull request against pass-docker with these updates.
Once acceptance-tests successfully run in CI in your pass-docker PR, and preferrably once you’ve done some additional manual spot checking while running pass-docker locally, go ahead and tag a new release in the Github UI for each of pass-ui, pass-ui-public, pass-auth and pass-acceptance-testing.
Here’s what you need to change manually before building a new image version in order to bring in code changes. If the docker compose service is not mentioned here, you do not need to make any manual changes. All images must be built manually using docker compose, following the docker compose rebuilding / updating steps except pass-core which is built by Maven.
pass-uiIn .env, by default, EMBER_GIT_BRANCH should have a value of main. If you need to point to a specific branch update the value of EMBER_GIT_BRANCH. You can use the name of a tag or a specific commit hash.
Manual testing can be done using the newly updated pass-docker to run the release locally. Acceptance testing is run automatically on GitHub against pass-docker/main