Post Release (Successful)
The release process consists of:
-
the release manager cutting the release
-
members of the Apache Causeway PMC verifying and voting on the release
-
the release manager performing post-release tasks, for either a successful or an unsuccessful vote (former documented below)
For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours. If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
This section describes the steps to perform if the vote has been successful.
Inform dev ML
Post the results to the dev@causeway.a.o
mailing list:
[RESULT] [VOTE] Apache Causeway Core release 2.2.0
using the body (alter last line as appropriate):
The vote has completed with the following result :
+1 (binding): ... list of names ...
+1 (non binding): ... list of names ...
-1 (binding): ... list of names ...
-1 (non binding): ... list of names ...
The vote is SUCCESSFUL.
I'll now go ahead and complete the post-release activities.
Release to Maven Central
We release from Maven Central before anything else; we don’t want to push the git tags (an irreversible action) until we know that this has worked ok. |
From the ASF Nexus repository, select the staging repository and select 'release' from the top menu.
This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
Set environment variables
As we did for the cutting of the release, we set environment variables to parameterize the following steps:
export CAUSEWAYJIRA=CAUSEWAY-9999 (1)
export CAUSEWAYTMP=/c/tmp (2)
export CAUSEWAYREL=2.2.0 (3)
export CAUSEWAYRC=RC1 (4)
export CAUSEWAYBRANCH=release-$CAUSEWAYREL-$CAUSEWAYRC
export CAUSEWAYART=causeway
env | grep CAUSEWAY | sort
1 | set to an "umbrella" ticket for all release activities. (One should exist already, created at the beginning of the development cycle now completing). |
2 | adjust by platform |
3 | adjust as required |
4 | adjust as necessary if there was more than one attempt to release |
Open up a terminal, and switch to the correct release branch:
git checkout $CAUSEWAYBRANCH
Update tags
Replace the -RCn
tag with another without the qualifier.
You can do this using the scripts/promoterctag.sh
script; for example:
sh scripts/promoterctag.sh $CAUSEWAYART-$CAUSEWAYREL $CAUSEWAYRC
This script pushes the tag under refs/tags/rel
.
As per Apache policy (communicated on 10th Jan 2016 to Apache PMCs), this path is 'protected' and is unmodifiable (guaranteeing the provenance that the ASF needs for releases).
Update JIRA
Close tickets
Close all JIRA tickets for the release, or moved to future releases if not yet addressed. Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
Mark the version as released
In JIRA, go to the administration section for the Apache Causeway project and update the version as being released.
In the Kanban view this will have the effect of marking all tickets as released (clearing the "done" column).
Close all released tickets
From the Releases page, review the status of all work items in the release to check that they are closed.
If any are not, open the tickets in the issue navigator (from the release page):
and then use "Bulk change" to transition through workflow:
Update Release Notes
In the main causeway
repo (ie containing the asciidoc source):
-
Generate release notes
From the root directory, generate the release notes for the current release, in AsciiDoc format; eg:
sh scripts/jira-release-notes.sh CAUSEWAY $CAUSEWAYREL > /tmp/$CAUSEWAYREL.adoc
This script uses 'jq' to parse JSON. See the script itself for details of how to install this utility.
-
Create a new
relnotes.adoc
filein
antora/components/relnotes/modules/ROOT/pages/yyyy/vvv/relnotes.adoc
-
where
yyyy
is the year -
vvv
is the version number
Copy the release notes (
/tmp/$CAUSEWAYREL.adoc
) into therelnotes.adoc
, recategorising if necessary -
-
Update the table in
antora/components/relnotes/ROOT/pages/about.adoc
Date of release, number of new features, improvements and bugs fixed.
-
Update
antora/components/relnotes/ROOT/nav.adoc
To reference these release notes.
-
update the
doap_causeway.rdf
file (which provides a machine-parseable description of the project) with details of the new release. Validate using the W3C RDF Validator service.For more on DOAP files, see these Apache policy docs. -
Update the STATUS file (in root of Apache Causeway' source) should be updated with details of the new release.
-
commit the changes
git add . git commit -m "$CAUSEWAYJIRA: updates release notes, STATUS and doap_causeway.rdf"
Release Source Zip
As described in the Apache documentation, each Apache TLP has a release/TLP-name
directory in the distribution Subversion repository at https://dist.apache.org/repos/dist.
Once a release vote passes, the release manager should svn add
the artifacts (plus signature and hash files) into this location.
The release is then automatically pushed to http://www.apache.org/dist/ by svnpubsub
.
Only the most recent release of each supported release line should be contained here, old versions should be deleted.
Each project is responsible for the structure of its directory. The directory structure of Apache Causeway reflects the directory structure in our git source code repo:
causeway/
core/
If necessary, checkout this directory structure:
svn co https://dist.apache.org/repos/dist/release/causeway causeway-dist
Next, add the new release into the appropriate directory.
The upd.sh
script can be used to automate this:
new_ver=$1
if [ $# -lt 1 ]; then
echo "usage: $(basename $0) version" 2>&1
exit 1
fi
# constants
fullname="causeway-bom"
repo_root=https://repository.apache.org/content/repositories/releases/org/apache/causeway
# file suffices
zip="source-release.zip"
asc="$zip.asc"
md5="$zip.md5"
sha1="$zip.sha1"
sha512="$zip.sha512"
for suffix in $zip $asc $md5 $sha1 $sha512
do
echo curl -O $repo_root/$fullname/$new_ver/$fullname-$new_ver-$suffix
curl -O $repo_root/$fullname/$new_ver/$fullname-$new_ver-$suffix
svn add $fullname-$new_ver-$suffix
done
sh upd.sh 2.2.0
The script downloads the artifacts from the Nexus release repository and adds the artifacts to subversion.
Manually delete any old files using svn delete
.
Double check that the files are correct; there is sometimes a small delay in the files becoming available in the release repository.
It should be sufficient to check just the md5
or .asc
files that these look valid (aren’t HTML 404 error pages):
cat *.md5
cat *.sha1
cat *.sha512
Assuming all is good, commit the changes:
svn commit -m "publishing causeway source releases to dist.apache.org"
If the files are invalid, then revert using svn revert . --recursive
and try again in a little while.
Final website updates
Apply any remaining documentation updates:
-
If there have been documentation changes made in other branches since the release branch was created, then merge these in.
-
If there have been updates to any of the schemas, copy them over:
-
copy the new schema(s) from
api/schema/src/main/resources/o.a.c.s.xxx
to its versioned:
antora/supplemental-ui/schema/xxx/xxx-ver.xsd
-
ensure the non-versioned is same as the highest versioned
antora/supplemental-ui/schema/xxx/xxx.xsd
-
-
Commit the changes:
git add . git commit -m "$CAUSEWAYJIRA: merging in final changes to docs"
We are now ready to generate the website.
Generate website
We use Antora to generate the site, setting up a document maintenance branches 2.2.0
and 3.2.0
.
These mirror the "rel/causeway-2.2.0" and "rel/causeway-3.2.0" (immutable) release tags, but are branches because they allow us to update the docs outside of formal releases.
The site.yml
(which can be in any branch) references these documentation branches, but uses the latest version support of Antora 3.x to reference the 3.2.0
version as "latest":
urls:
latest_version_segment: latest
This approach also means that the top-level index.html
(from the Antora template) does not need to be modified; it can simply refer to "latest".
To avoid duplicates in the Algolia search index, we also only index the "latest" directory.
Create 2.x.0 doc branch
-
We create the
2.2.0
branch, at the rel/causeway-2.2.0 release tag.git checkout -b 2.2.0 git reset --hard rel/causeway-2.2.0
-
update all
antora.yml
files to use the latest branch (2.2.0):find . -name antora.yml -exec sed -i 's/latest/2.2.0/g' {} \;
-
update the version for the petclinic tutorial:
antora/components/tutorials/antora.ymlasciidoc: attributes: tag-version: '2.2.0' jdk-version: '11'
-
build framework
pushd bom mvnd clean install -T1C -DskipTests -Dgithub popd
-
build and link to the module tooling jar, as per doc tooling prereqs process
-
generate the website:
sh preview.sh
-
if any files have changed, then commit:
git add . git commit -m "$CAUSEWAYJIRA: updates docs on new release branch"
-
Commit all these changes:
git add . git commit -m "$CAUSEWAYJIRA: bumps antora.yml versions to $CAUSEWAYREL"
-
Push the documentation branch:
git push origin 2.2.0 -u
Create 3.x.0 doc branch
-
We create the
3.2.0
branch, at the rel/causeway-3.2.0 release tag.git checkout -b 3.2.0 git reset --hard rel/causeway-3.2.0
-
update all
antora.yml
files to use the latest branch (3.2.0):find . -name antora.yml -exec sed -i 's/latest/3.2.0/g' {} \;
-
update the version for the petclinic tutorial:
antora/components/tutorials/antora.ymlasciidoc: attributes: tag-version: '3.2.0' jdk-version: '17'
-
build framework
pushd bom mvnd clean install -T1C -DskipTests -Dgithub popd
-
build and link to the module tooling jar, as per doc tooling prereqs process
-
generate the website:
sh preview.sh
-
if any files have changed, then commit:
git add . git commit -m "$CAUSEWAYJIRA: updates docs on new release branch"
-
Commit all these changes:
git add . git commit -m "$CAUSEWAYJIRA: bumps antora.yml versions to $CAUSEWAYREL"
-
Push the documentation branch:
git push origin 3.2.0 -u
Generate the site
To build the site, we need to update the site.yml
.
This can be done from any branch, normally the release branch ($CAUSEWAYBRANCH
) or master
.
All that will be picked up from this branch is the supplementary-ui files (top-level index) and the site.yml playbook that identifies which branch(es) to include in the website.
|
-
Update
site.yml
usingsite.NEXT.yml
: -
move
site.yml
to one side, and replace withsite.NEXT.yml
:pushd antora/playbooks mv site.yml site.ORIG.yml mv site.NEXT.yml site.yml popd
-
update the new
site.yml
, eg:site.ymlcontent: sources: - url: . start_path: antora/components/docs # docs branches: [2.2.0, 3.2.0] # ... - url: . start_path: viewers/wicket/adoc # vw branches: [2.2.0, 3.2.0]
-
check that the attributes are correct.
site.ymlasciidoc: attributes: page-causewayprevv2: "..." (1) page-causewayprevv3: "..." (2) page-causewayrelv2: "..." (3) page-causewayrelv3: "..." (4)
1 needs to be (the current) 2.2.0
2 needs to be (the current) 3.2.0
3 needs to be set to the next likely release version for v2. 4 needs to be set to the next likely release version for v3 branch -
commit the changes
git add . git commit -m "$CAUSEWAYJIRA: updates site.yml in readiness for website generation"
-
generate the website:
sh preview.sh -AS
This will write to
antora/target/site
; we’ll use the results in the next section. -
Revert
site.yml
Restore the original
site.yml
file.
Publish website
We now copy the results of the Antora website generation over to the causeway-site
repo:
-
in the
causeway-site
repo, check out theasf-site
branch:cd ../causeway-site git checkout asf-site git pull --ff-only
-
still in the
causeway-site
repo, run thecopyover.sh
script:sh copyover.sh
This deletes all the files in
content/
except for theschema
andversions
directories, and copies the generated Antora site tocauseway-site
repo’scontents
directory:#!/usr/bin/env bash pushd content for a in $(ls -1 | grep -v schema | grep -v versions) do rm -rf $a done popd pushd ../causeway cp -Rf antora/target/site/* ../causeway-site/content/. popd git add .
-
Commit the changes and preview:
git commit -m "updates website" sh preview.sh
-
If everything looks ok, then push the changes to make live, and switch back to the
causeway
repo:git push origin asf-site
Update the Algolia search index
We use Algolia to build our search index.
-
If required, create a
algolia.env
file holding theAPP_ID
and the adminAPI_KEY
, in the root ofcauseway-site
; see appendix for details. -
If required, update the
algolia-config.json
file; see appendix for details.In particular, update the
stop_urls
property with any paths that should not be crawled.Our policy is to only index the most recent version. This avoids lots of duplication in the index; previous versions of the page are easily accessible. -
Use the Algolia-provided docker image to crawl the web pages and create the search index:
pushd content docker run -it --env-file=../algolia.env -e "CONFIG=$(cat ../algolia-config.json | jq -r tostring)" algolia/docsearch-scraper:v1.16.0 popd
This posts the index up to the Algolia site.
Merge in release branch
Because we release from a branch, the changes made in the branch should be merged back from the release branch back into the master
branch.
In the causeway
repo:
RC=RC1 (1)
git checkout master
git pull
git merge release-2.2.0-$RC
git push origin master
git branch -d release-2.2.0-$RC
git push origin release-2.2.0-$RC --delete
1 | adjust RC number as required |
Bump baselines for nightly/weekly builds
Main repo (weekly builds)
In the main repo, in .github/workflows
, update the BASELINE
variable in all scripts:
-
for example, in
ci-build-artifacts-no-push-maven.yml
:.github/workflows/ci-build-artifacts-no-push-maven.ymljobs: build: env: BASELINE: 2.2.0
-
in
ci-build-site-no-push.yml
:.github/workflows/ci-build-site-no-push.ymljobs: build: env: BASELINE: 2.2.0
-
commit and push:
git add . git commit -m "$CAUSEWAYJIRA: bumps BASELINE to latest release version"
Nightly build repo
In the apache-causeway-committers/causeway-nightly
repo, similarly bump the versions of the BASELINE_MAIN
variable.
-
first update your local repo:
git fetch git reset --hard origin/master
-
update the
apache-causeway-ci-nightly.yml
file:.github/workflows/apache-causeway-ci-nightly.ymljobs: build: name: build, site, build/push reference app runs-on: ubuntu-latest env: # to be shared among all steps of this job BASELINE_MAIN: 2.2.0 BASELINE_EDGE: 3.2.0
-
update any other CI scripts that might exist there.
-
commit and push:
git add . git commit -m "$CAUSEWAYJIRA: bumps BASELINE to latest release version"
Update starter projects
As explained in cutting a release,for each of the two starter apps, we maintain eight (!) branches:
-
v2-jpa
;v2-jdo
;v3-jpa
;v3-jdo
These are intended to reference the most recently released version, the first demonstrating persistence using JDO, the second using JPA. These are the branches referenced from the home page and getting started pages of the website.
-
v2-jpa-SNAPSHOT
;v2-jdo-SNAPSHOT
;v3-jpa-SNAPSHOT
;v3-jdo-SNAPSHOT
These reference the most current snapshot nightly build.
The general idea is that a release will fast-forward v2-jpa
to v2-jpa-SNAPSHOT
and similarly moves v2-jdo
up to v2-jdo-SNAPSHOT
, and then repeat the process for v3.
The non-SNAPSHOT builds should always reference the most recently release of v2 or v3.
In order that we don’t break the starter apps while a release is being voted on, we do the changes in work branches, $CAUSEWAYBRANCH-jpa
and $CAUSEWAYBRANCH-jdo
(where $CAUSEWAYBRANCH
is "release-2.0.0-RC1", or "release-3.0.0-RC1" etc).
Now that the release is complete, tidy up these branches and then set up the -SNAPSHOT
branches as required.
The v{2,3}-{jpa,jdo} branches should always work against the most recent release, whereas the v{2,3}-{jpa,jdo}-SNAPSHOT reference more recent nightly builds if necessary.
|
Update the reference app
The reference app has a configuration property causeway.viewer.common.application.version
(in application.yml); this should be updated.
Update the ASF Reporter website
Log the new release in the ASF Reporter website.
Announce the release
Announce the release to users mailing list.
For example, for a release of Apache Causeway Core, use the following subject:
[ANN] Apache Causeway version 2.2.0 Released
And use the following body (summarizing the main points as required):
The Apache Causeway team is pleased to announce the release of Apache Causeway 2.2.0.
New features in this release include:
* ...
Full release notes are available on the Apache Causeway website at [1].
You can access this release directly from the Maven central repo [2].
Alternatively, download the release and build it from source [3].
Enjoy!
--The Apache Causeway team
[1] https://causeway.apache.org/relnotes/latest/about.html
[2] https://search.maven.org
[3] https://causeway.apache.org/docs/latest/downloads/how-to.html
Announce on announce@apache.org
This mailing list is for official project announcements, including release announcements. Posting to this mailing list is highly recommended:
"sending your news to announce@ helps amplify your message to thousands of subscribers, and be included in official ASF promotions, including the Weekly News Round-ups (published every Friday; read by members of the media/analyst community --SD News publishes weekly updates on Apache projects from the Round-ups)"
email out to Apache PMCs
There are strict guidelines regarding posting to announce@apache.org, which is a moderated list. The message must:
-
be sent from your apache.org address;
-
be in PLAINTEXT (no HTML mail, no embedded links) and with no attachments
-
contain [ANNOUNCE] or [ANN] before a clear subject line
eg:
[ANNOUNCE] Apache PROJECTNAME v2.3 released
. -
include your project boilerplate ~10-60 words (DOAP = description of a project; eg. https://projects.apache.org/project.html?bookkeeper )
-
include a link to the project homepage or download source(s)
Update BASELINE for the (non-ASF) nightly builds
Nightly builds of the framework’s packages are available in two different locations:
-
First, they can be found as packages of the main github.com/apache/causeway repo; these can be accessed using your github credentials.
Bump the
BASELINE
variable in ci-build-artifacts-no-push-maven.yml (workflow file). -
But they are also to be found as packages within the (non-ASF) github.com/apache-causeway-committers/causeway-nightly repo; no credentials are required for these because the git repo is used as a package repository directly.
Bump the
BASELINE
variable in apache-causeway-ci-nightly.yml (workflow file).