Post Release (Successful)

The release process consists of:

the release manager cutting the release
members of the Apache Isis 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@isis.a.o mailing list:

[RESULT] [VOTE] Apache Isis Core release {page-isisrel}

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 ISISJIRA=ISIS-9999                           (1)
export ISISTMP=/c/tmp                               (2)
export ISISREL={page-isisrel}                           (3)
export ISISRC=RC1                                   (4)
export ISISBRANCH=release-$ISISREL-$ISISRC
export ISISART=isis

env | grep ISIS | 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 $ISISBRANCH

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 $ISISART-$ISISREL $ISISRC

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 Isis 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:

Create new JIRA

Create a new JIRA ticket as a catch-all for the next release.

Update Release Notes

In the main isis 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 ISIS $ISISREL > /tmp/$ISISREL.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 file

in 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/$ISISREL.adoc) into the relnotes.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_isis.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 Isis' source) should be updated with details of the new release.

commit the changes

git add .
git commit -m "$ISISJIRA: updates release notes, STATUS and doap_isis.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 Isis reflects the directory structure in our git source code repo:

isis/
  core/

If necessary, checkout this directory structure:

svn co https://dist.apache.org/repos/dist/release/isis isis-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="isis-bom"
repo_root=https://repository.apache.org/content/repositories/releases/org/apache/isis

# 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{page-isisrel}

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 isis 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.i.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 "$ISISJIRA: merging in final changes to docs"

We are now ready to generate the website.

Generate website

We use Antora to generate the site, not only the version being release but also any previous versions listed in site.yml. This is done using the content.sources.url[].branches properties. We use branches for all cases - note that the branch name appears in the generated UI. If there are patches to the documentation, we move the branches.

We therefore temporarily modify all of the antora.yml files (and update index.html) file and create a branch for this change; then we update site.yml with a reference to that new branch. All of this is changed afterwards.

Create doc branch

First, we update all versions in antora.yml:

Update all antora.yml files:

find . -name antora.yml -exec sed -i 's/latest/{page-isisrel}/g' {} \;

Commit all these changes:

git add .
git commit -m "$ISISJIRA: bumps antora.yml versions to $ISISREL"

We now create a branch to reference in the site.yml, later on.

We create the {page-isisrel} branch.

This mirrors the "rel/isis-{page-isisrel}" used for the formal (immutable) release tag, but is a branch because it allows us to move it, and must have this simplified name as it is used in the "edit page" link of the site template.
```
git branch {page-isisrel}
git push origin {page-isisrel}
```

Finally, revert the last commit (backing out changes to antora.yml files):

git revert HEAD

Update `index.html` & `site.yml` & generate

Lastly, we update index.html and then site.yml

With the home page of the website, antora/supplemental-ui/index.html, update any mention of latest → {page-isisrel}

This should be in hyperlinks, <a href="docs/…">

that this isn’t performed in the docs branch (previous section) because the supplemental files are not versioned as a doc component:
Now update site.yml

This will reference the new branch, and any previous branches. Every content source needs to be updated:
- branches: HEAD → branches: [2.0.0-M5, 2.0.0-M6, … , {page-isisrel}]

commit this change, too (there’s no need to push):

git add .
git commit -m "$ISISJIRA: updates references to version in index.html and site.yml"

We are now in a position to actually generate the Antora website. (NOTE, this needs to be performed in the ../isis directory because Antora currently doesn’t support git worktrees)

build prereqs

git checkout $ISISBRANCH
pushd bom
mvn clean install -DskipTests -Dreleased
popd
mvn clean install -pl core/config
mvn -D module-tooling -D skip.essential install -DskipTests

generate the website:
```
sh preview.sh
```
This will write to antora/target/site; we’ll use the results in the next section.

Finally, revert the last commit (backing out changes to site.yml):

git revert HEAD

Publish website

We now copy the results of the Antora website generation over to the isis-site repo:

in the isis-site repo, check out the asf-site branch:

cd ../isis-site

git checkout asf-site
git pull --ff-only

still in the isis-site repo, run the copyover.sh script:

sh copyover.sh

This deletes all the files in content/ except for the schema and versions directories, and copies the generated Antora site to isis-site repo’s contents 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 ../isis
cp -Rf antora/target/site/* ../isis-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 isis repo:
```
git push origin asf-site
```

Update the Algolia search index

Create a algolia.env file holding the APP_ID and the admin API_KEY, in the root of isis-site:

algolia.env

APPLICATION_ID=...
API_KEY=...

This file should not be checked into the repo, because the API_KEY allows the index to be modified or deleted.

We use the Algolia-provided docker image for the crawler to perform the search (as per the link:as per docs):

cd content
docker run -it --env-file=../algolia.env -e "CONFIG=$(cat ../algolia-config.json | jq -r tostring)" algolia/docsearch-scraper:v1.16.0

This posts the index up to the Algolia site.

Additional config options for the crawler can be found here.

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 isis repo ():

RC=RC1                                                (1)
git checkout master
git pull
git merge release-{page-isisrel}-$RC
git push origin --delete release-{page-isisrel}-$RC
git branch -d release-{page-isisrel}-$RC

1	adjust RC number as required

Bump {page-isisrel} in `site.yml`

In site.yml file, bump the version of {page-isisrel} and also {page-isisprev}, and commit.

Update starter projects

As explained in cutting a release,for each of the two starter apps, we maintain four branches:

jdo and jpa

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.
jdo-SNAPSHOT and jpa-SNAPSHOT

These reference the most current snapshot nightly build.

The general idea is that a release will fast-forward jdo to jdo-SNAPSHOT and similarly moves jpa up to jpa-SNAPSHOT, bumping to the newly released version of the framework in the process.

In order that we don’t break the starter apps while a release is being voted on, we do the changes in work branches, $ISISBRANCH-jdo and $ISISBRANCH-jpa.

Now that the release is complete, tidy up these branches and then set up the -SNAPSHOT branches as required.

The jdo and jpa branches should always work against the most recent release, whereas the jdo-SNAPSHOT and jpa-SNAPSHOT can reference more recently nightly builds if necessary.

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 Isis Core, use the following subject:

[ANN] Apache Isis version {page-isisrel} Released

And use the following body (summarizing the main points as required):

The Apache Isis team is pleased to announce the release of Apache Isis {page-isisrel}.

New features in this release include:

* ...

Full release notes are available on the Apache Isis 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 Isis team

[1] https://isis.apache.org/relnotes/{page-isisrel}/about.html
[2] https://search.maven.org
[3] https://isis.apache.org/docs/{page-isisrel}/downloads/how-to.html

Blog post

Log onto the Apache blog and create a new post. Copy-n-paste the above mailing list announcement should suffice.

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)"

— Sally Khudairi
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)

Examples: https://lists.apache.org/list.html?announce@apache.org

Announce the release using the @ApacheIsis Twitter account.

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/isis 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-isis-committers/isis-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-isis-ci-nightly.yml (workflow file).