We currently have a brand new release process re-implemented using GitHub Workflow, this means that each single step required by the old process is now defined as a single GitHub Action.
Publishing Maven Snapshot artifacts
Now we have a brand new GitHub workflow named Publish Snapshot Artifacts publishing Maven artifacts in the Apache Maven repository.
This workflow is automatically triggered by any new commit against the master branch.
There also is an equivalent GitHub workflow named Publish Release Artifacts publishing release artifacts and it can be triggered manually after the vote passes but it is currently disabled due to the lack of GPG secrets configured in our GitHub repo.
Creating Release Candidate Branch
In order to create a new release branch you only need to:
- Access the Create Release Candidate workflow from the Actions tab
- Click on the Run workflow button
- Select the specific branch to use as the new release candidate
- Set the Release Candidate Tag, for example RC0
- Press the Run workflow (green button)
- Wait for the entire execution
- Access the Publish Release Candidate in ASF SVN workflow from the Actions tab (work in progress...)
- Click on the Run workflow button
- Set the Release Candidate branch, for example release-2.27-RC1
- Press the Run workflow button
The GitHub workflow will perform the following tasks:
- Checkout the code in the GitHub VM
- Configure OpenJDK 11 Temurin
- Extract the project version from the Maven POM as a GitHub output variable
- Create the new branch
- Update CHANGES.txt, build.xml and all the poms
- Run the Ant build
- Run the Maven build (if we want to push artifacts on public repos)
- Check licenses using Apache RAT
- Commit and push the new branch
- Upload artifacts as GitHub release assets
- Build and push Docker images to our Docker Hub repo (https://hub.docker.com/r/apache/manifoldcf)
- Download all the artifacts generated by GitHub in a local folder
- Copy the script sign-release-artifacts.sh in the local folder with the generated artifacts and run it: ./sign-release-artifacts.sh <GPG_LOCAL_USER> <MANIFOLDCF_VERSION> (for example: ./sign-release-artifacts.sh piergiorgio@apache.org 2.27-dev)
- Upload all the generated file hashes into the Release Candidate created on GitHub
- Commit all the release artifacts including the file hashes in the ASF distribution folder (https://dist.apache.org/repos/dist/dev/manifoldcf/)
- Execute the following Maven command in order to publish all the artifacts in the staging Nexus repo:
mvn clean deploy -DskipTests -DskipITs -Dmaven.javadoc.skip=true -Papache-release --threads=1
The final result is published as a GitHub release including all the artifacts as the following example related to the 2.27-RC1:
Before releasing
Before you cut a release, it's always a good idea to run all the tests you can on the software. Also necessary is a "rat" run, which detects unknown or incorrect licenses on source files. See the complete checklist below.
- Download the dependencies for building and testing: ant make-core-deps make-deps (You will need Apache Ant 1.10.x installed for this step)
- Reproduce the artifacts locally using the create-release-candidate-only-artifacts.sh script (Ant 1.10.x and Maven 3.9.x required)
- Check licenses: mvn -pl . apache-rat:check. You are interested in verifying that there are zero files with unapproved licenses. (This comes at the very start of a long report.) You will need Apache Maven 3.9.x installed for this step.
- Run standard integration tests with ant test command or ant test-dr test-hs. If you have PostgreSQL installed and MySQL, run those too (ant test-pg test-my).
- Run the UI tests (ant uitest). You'll need Python 2.7+ for these.
- Validate all the artifacts (signatures and comparing checksums from GitHub or the ASF distribution folder).
Calling the vote
Once the artifact has been uploaded to people.apache.org, you should call a vote to release the artifact. This involves sending an email to dev@manifoldcf.apache.org, with the title "[VOTE] Release Apache ManifoldCF xxxx RCnnn". In the vote email, mention where the artifacts can be downloaded from (https://github.com/apache/manifoldcf/releases/tag/x.xx-RC0). The vote must have three +1's from committers, and must be open at least 72 hours.
If the vote does not pass
If the vote does not pass, this usually implies that fixes will be made and a new RC created. Fixes usually are committed to trunk first and then pulled up into the release branch.
If the vote passes
When the vote passes, you should rename manually the RC tag and all the RC artifacts included in the release removing the -RCx suffix from it using the Releases tab in GitHub.
- Rename the GitHub branch from release-<VERSION>-RC<RC_VERSION> to release-<VERSION>-branch (example: from release-2.27-RC2 to release-2.27-branch)
- Rename all the artifacts removing the -dev- prefix (example from apache-manifoldcf-2.27-dev-bin.tar.gz to apache-manifoldcf-2.27-bin.tar.gz)
- Create a new folder named apache-manifoldcf-<VERSION> in the ASF SVN folder https://dist.apache.org/repos/dist/release/manifoldcf/
- Move and rename the release artifacts from the dev folder into the release folder in the ASF SVN from https://dist.apache.org/repos/dist/dev/manifoldcf/ to https://dist.apache.org/repos/dist/release/manifoldcf/
- Commit all the changes in SVN
The release includes the artifacts just voted:
DO NOT REGENERATE THE ARTIFACTS - the community has voted on them and they are the only legal copies you should distribute.
Publish the Maven Release artifacts in the following way:
- Then access the ASF Nexus Repository → Staging repositories: https://repository.apache.org/#stagingRepositories
- Select the ManifoldCF Staging repo named orgapachemanifoldcf-xxxx
- Look at the Content tab to check if all the artifacts are correctly published as expected
- Press the Close button and wait until the end of the procedure
- Press the Release button and wait until the end of the procedure
Publish the Docker Image Release in the following way:
- From the Actions tab in GitHub start the Create Docker Image workflow
- Select the release and press the Run workflow button
- Wait for the build process
- Verify the new Docker Image running locally the following command:
docker run -p 8345:8345 apache/manifoldcf:<VERSION>
Updating the website
ASF Pelican CMS is now deprecated and we should migrate to GitHub pages as soon as possible.
The second step is to modify the MCF site to reflect the new release.
The web contents can be modified directly in HTML format in the following GitHub project:
https://github.com/apache/manifoldcf-site
The asf-site branch is including the HTML contents so we can modify directly pushing all the needed changes.
Regenerating the contents using the legacy way from GitHub (deprecated)
Currently due to the migration to GitHub the unique way to regenerate the contents from the docbook format is the following:
- Clone the MCF SDK GitHub project: https://github.com/apache/manifoldcf-sdk
- Run this command: ./run.sh init MCF_VERSION (TBD, this step is currently working on releases published on SVN, work in progress for the new releases on GitHub)
- Add the release to build.xml (and remove any older releases we no longer want to publish information for)
- Add the release download links to all of the various language's download.xml pages
- On the download pages, be sure to change the previous release so it is no longer downloaded from dyn/closer.cgi, and is instead downloaded from the Apache archive server
- Update the index.xml pages to announce the new release
- Generate the new contents with: ./run-site.sh build
- Clone the MCF Site GitHub project: https://github.com/apache/manifoldcf-site
- Switch to the pelican-staging branch
- Push the new website in the pelican-staging and check the staging website at https://manifoldcf-pelican.staged.apache.org/
- If everything is ok push all the contents in the pelican-staging branch
- Switch to the asf-site branch and push all the contents in it
- Create a new tag with the MCF_VERSION