= Post Release (Successful)

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

The release process consists of:

* the release manager xref:comguide:ROOT:cutting-a-release.adoc[cutting the release]

* members of the Apache Causeway PMC xref:comguide:ROOT:verifying-releases.adoc[verifying] and voting on the release

* the release manager performing post-release tasks, for either a successful or an xref:comguide:ROOT:post-release-unsuccessful.adoc[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:

[source,subs="attributes+"]
----
[RESULT] [VOTE] Apache Causeway Core release {page-causewayrel}
----

using the body (alter last line as appropriate):

[source]
----
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

CAUTION: 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 http://repository.apache.org[ASF Nexus repository], select the staging repository and select 'release' from the top menu.

image::release-process/nexus-release-1.png[width="600px"]

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:

[source,bash,subs="attributes+"]
----
export CAUSEWAYJIRA=CAUSEWAY-9999                           # <.>
export CAUSEWAYTMP=/c/tmp                               # <.>
export CAUSEWAYREL={page-causewayrel}                           # <.>
export CAUSEWAYRC=RC1                                   # <.>
export CAUSEWAYBRANCH=release-$CAUSEWAYREL-$CAUSEWAYRC
export CAUSEWAYART=causeway

env | grep CAUSEWAY | sort
----
<.> set to an "umbrella" ticket for all release activities.
(One should exist already, xref:comguide:ROOT:post-release-successful.adoc#create-new-jira[created at] the beginning of the development cycle now completing).
<.> adjust by platform
<.> adjust as required
<.> adjust as necessary if there was more than one attempt to release

Open up a terminal, and switch to the correct release branch:

[source,bash,subs="attributes+"]
----
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:

[source,bash,subs="attributes+"]
----
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 link:https://issues.apache.org/jira/plugins/servlet/project-config/CAUSEWAY/versions[administration section] for the Apache Causeway project and update the version as being released.

In the link:https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=87[Kanban view] this will have the effect of marking all tickets as released (clearing the "done" column).

[#close-all-released-tickets]
=== Close all released tickets

From the link:https://issues.apache.org/jira/projects/CAUSEWAY?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=released-unreleased[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):

image::release-process/jira-open-release-in-navigator.png[width=800px]

and then use "Bulk change" to transition through workflow:

image::release-process/jira-bulk-tool.png[width=200px]

[#create-new-jira]
=== Create new JIRA

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

== 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:
+
[source,bash,subs="attributes+"]
----
sh scripts/jira-release-notes.sh CAUSEWAY $CAUSEWAYREL > /tmp/$CAUSEWAYREL.adoc
----
+
[NOTE]
====
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/$CAUSEWAYREL.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_causeway.rdf` file (which provides a machine-parseable description of the project) with details of the new release.
Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service.
+
TIP: For more on DOAP files, see these link:http://projects.apache.org/doap.html[Apache policy docs].

* Update the link:https://github.com/apache/causeway/blob/master/STATUS[STATUS] file (in root of Apache Causeway' source) should be updated with details of the new release.

* commit the changes
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: updates release notes, STATUS and doap_causeway.rdf"
----

== Release Source Zip

As described in the link:http://www.apache.org/dev/release-publishing.html#distribution_dist[Apache documentation], each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at link:https://dist.apache.org/repos/dist[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/[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:

[source]
----
causeway/
  core/
----

If necessary, checkout this directory structure:

[source,bash]
----
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:

[source,bash]
.upd.sh
----
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
----

[source,bash,subs="attributes+"]
----
sh upd.sh {page-causewayrel}
----

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

[source,bash,subs="attributes+"]
----
cat *.md5
cat *.sha1
cat *.sha512
----

Assuming all is good, commit the changes:

[source,subs="attributes+"]
----
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.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:
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: merging in final changes to docs"
----

We are now ready to xref:#generate-website[generate the website].

[#generate-website]
== Generate website

We use Antora to generate the site, not only the version being released but also any previous versions listed in `site.yml`; each of these are tags.
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.

We also use the link:https://docs.antora.org/antora/latest/playbook/urls-latest-version-segment/[latest version] support of Antora 3.x so that the most recent version is made available as "latest".
This has two benefits: first, the top-level `index.html` (in `supplemental-ui`) does not need to be updated, and secondly, this improves search engine results as there will always be a `latest` version.


[#create-doc-branch]
=== Create doc branch

First, we update all versions in `antora.yml`:

* Update all `antora.yml` files:
+
[source,bash,subs="attributes+"]
----
find . -name antora.yml -exec sed -i 's/latest/{page-causewayrel}/g' {} \;
----

* Commit all these changes:
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: bumps antora.yml versions to $CAUSEWAYREL"
----

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

* We create the `{page-causewayrel}` branch.
+
This mirrors the "rel/causeway-{page-causewayrel}" 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.
+
[source,bash,subs="attributes+"]
----
git branch {page-causewayrel}
git push origin {page-causewayrel}
----

Now we make sure that the docs in the new doc branch are actually up-to-date.
(There is no need to update `site.yml`, because at this stage it continues to refer to the `HEAD` branch):

* checkout the branch:
+
[source,bash,subs="attributes+"]
----
git checkout {page-causewayrel}
----

* build prereqs
+
[source,bash,subs="attributes+"]
----
pushd bom
mvnd clean install -T1C -DskipTests -Dgithub
popd
mvnd -D module-tooling -D skip.essential install -DskipTests
----

* generate the website:
+
[source,bash,subs="attributes+"]
----
sh preview.sh
----

* if any files have changed, then commit:
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: updates docs on new release branch"
----


* push the updated doc branch:
+
[source,bash,subs="attributes+"]
----
git push origin {page-causewayrel}
----


[#generate-the-site]
=== Generate the site


To build the site (referencing the current release and all previous releases), we need to update the `site.yml`.
This is done in the release branch (`$CAUSEWAYBRANCH`), _not_ in the documentation branch for the current release ({page-causewayrel}).

* Switch to the release branch:
+
[source,bash,subs="attributes+"]
----
git checkout $CAUSEWAYBRANCH            #<.>
----
<.> will be before the documentation branch of the current release

* Update with the documentation branch for the current release ({page-causewayrel})
+
[source,bash,subs="attributes+"]
----
git merge {page-causewayrel} --ff-only  #<.>
----
<.> move forward to incorporate any changes made thus far on the documentation branch


* Now, revert the commit that changed the `antora.yml` files in the documentation branch
+
If there were no doc changes, then you can simply use:
+
[source,bash,subs="attributes+"]
----
git revert HEAD
----
+
Otherwise, locate the `shaId` of the commit that applied the change and revert appropriately.



Now, update `site.yml` using `site.NEXT.yml`:

* move `site.yml` to one side, and replace with `site.NEXT.yml`:
+
[source,bash,subs="attributes+"]
----
pushd antora/playbooks
mv site.yml      site.ORIG.yml
mv site.NEXT.yml site.yml
popd
----

* update the new `site.yml`, eg:
+
[source,yaml,subs="attributes+"]
.site.yml
----
content:
  sources:
    - url: .
      start_path: antora/components/docs # docs
      branches: [2.0.0-M5, ...  2.0.0-RC3]
      # ...
    - url: .
      start_path: viewers/wicket/adoc # vw
      branches: [2.0.0-M5, ... 2.0.0-RC3]
----

* check that the attributes are correct.
+
[source,yaml,subs="attributes+"]
.site.yml
----
asciidoc:
  attributes:
    page-causewayprev: "..."    #<.>
    page-causewayrel: "..."     #<.>
----
<.> needs to be (the current) `{page-causewayrel}`
<.> needs to be set to the _next_ likely release version.

* commit the changes
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: updates site.yml in readiness for website generation"
----


We are ready to actually generate the Antora website.

* generate the website:
+
[source,bash,subs="attributes+"]
----
sh preview.sh -AS
----
+
This will write to `antora/target/site`; we'll use the results in the xref:#publish-website[next section].


=== Revert site.yml

Finally, restore the original `site.yml` file:

* move the edited `site.yml` to `site.NEXT.yml` (in readiness for the _next_ release), and restore:
+
[source,bash,subs="attributes+"]
----
pushd antora/playbooks
mv site.yml      site.NEXT.yml
mv site.ORIG.yml site.yml
popd
----

* commit
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: reverts site.yml"
----


include::partial$publish-and-index-website.adoc[]



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

[source,bash,subs="attributes+"]
----
RC=RC1                                                <.>
git checkout master
git pull
git merge release-{page-causewayrel}-$RC
git push origin master
git branch -d release-{page-causewayrel}-$RC
git push origin release-{page-causewayrel}-$RC --delete
----
<.> 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`:
+
[source,yml,subs="attributes+"]
..github/workflows/ci-build-artifacts-no-push-maven.yml
----
jobs:
  build:

    env:
      BASELINE: {page-causewayrel}
----

* in `ci-build-site-no-push.yml`:
+
[source,yml,subs="attributes+"]
..github/workflows/ci-build-site-no-push.yml
----
jobs:
  build:

    env:
      BASELINE: {page-causewayrel}
----

* commit and push:
+
[source,bash,subs="attributes+"]
----
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:
+
[source,bash,subs="attributes+"]
----
git fetch
git reset --hard origin/master
----

* update the `apache-causeway-ci-nightly.yml` file:
+
[source,yml,subs="attributes+"]
..github/workflows/apache-causeway-ci-nightly.yml
----
jobs:
  build:
    name: build, site, build/push reference app
    runs-on: ubuntu-latest
    env:
      # to be shared among all steps of this job
      BASELINE_MAIN: {page-causewayrel}
      BASELINE_EDGE: 3.0.0-M1
----
+
NOTE: We leave `BASELINE_EDGE` unchanged for the moment; we will update these release notes when we switch to the v3 release branch.

* update any other CI scripts that might exist there.

* commit and push:
+
[source,bash,subs="attributes+"]
----
git add .
git commit -m "$CAUSEWAYJIRA: bumps BASELINE to latest release version"
----

== Update starter projects

As explained in xref:cutting-a-release.adoc#update-starter-apps[cutting a release],for each of the two starter apps, we maintain four branches:

* `jpa` and `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.

* `jpa-SNAPSHOT` and `jdo-SNAPSHOT`
+
These reference the most current snapshot nightly build.

The general idea is that a release will fast-forward `jpa` to `jpa-SNAPSHOT` and similarly moves `jdo` up to `jdo-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, `$CAUSEWAYBRANCH-jpa` and `$CAUSEWAYBRANCH-jdo`.

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

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


== Update the reference app

The link:https://github.com/apache/causeway-app-referenceapp[reference app] has a configuration property `causeway.viewer.common.application.version` (in link:https://github.com/apache/causeway-app-referenceapp/blob/master/domain/src/main/resources/application.yml#L91[application.yml]); this should be updated.




== Update the ASF Reporter website

Log the new release in the link:https://reporter.apache.org/addrelease.html?causeway[ASF Reporter website].

== Announce the release

Announce the release to link:mailto:users@causeway.apache.org[users mailing list].

For example, for a release of Apache Causeway Core, use the following subject:

[source,subs="attributes+"]
----
[ANN] Apache Causeway version {page-causewayrel} Released
----

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

[source,subs="attributes+"]
----
The Apache Causeway team is pleased to announce the release of Apache Causeway {page-causewayrel}.

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

== Blog post

link:https://blogs.apache.org/roller-ui/login.rol[Log onto] the http://blogs.apache.org/causeway/[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:

[quote, Sally Khudairi, email out to Apache PMCs]
"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)"

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: link:https://lists.apache.org/list.html?announce\@apache.org[https://lists.apache.org/list.html?announce@apache.org]


== Social Media

Announce the release using the `@ApacheCauseway` 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 link:https://github.com/apache/causeway[github.com/apache/causeway] repo; these can be accessed using your github credentials.
+
Bump the `BASELINE` variable in link:https://github.com/apache/causeway/blob/master/.github/workflows/ci-build-artifacts-no-push-maven.yml#L20[ci-build-artifacts-no-push-maven.yml] (workflow file).

* But they are also to be found as packages within the (non-ASF) link:https://github.com/apache-causeway-committers/causeway-nightly[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 link:https://github.com/apache-causeway-committers/causeway-nightly/blob/0fdea0c4e7419b40acc9a03746e4c3cac3f262b2/.github/workflows/apache-causeway-ci-nightly.yml#L15[apache-causeway-ci-nightly.yml] (workflow file).
