[[verifying-releases]]
= Verifying a Release

: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 verifying and voting on the release (documented below)
* the release manager performing post-release tasks, for either a xref:comguide:ROOT:post-release-successful.adoc[successful] or an xref:comguide:ROOT:post-release-unsuccessful.adoc[unsuccessful] vote.

This section describes some guidance on what a voter (members of the Apache Causeway PMC and anyone else who wishes) is expected to do before casting their vote in order to verify a release.

== Background

Whenever a release manager announces a vote on a release (as per the xref:comguide:ROOT:cutting-a-release.adoc#start-voting-thread-on-dev-mailing-list[release process]) on the xref:docs:support:mailing-list.adoc#mailing-lists[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release.
Anyone else can also vote, but only members of the Apache Causeway PMC's vote are binding.

Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:

* a source zip file + corresponding signature (signed by the release manager, which is in the ASF web of trust and in our KEYS file)
* all source files have the Apache license (this is ensured by the running of the rat plugin prior to release; you could run it on the unzipped source)
* all dependencies are appropriately licensed; see the `DEPENDENCIES` file which is automatically generated from the POMs plus the supplemental-models.xml file

Note that the binaries are _not_ an ASF release, they merely exist on the Maven central repo as a convenience.
That said, you might also want to verify the release by pulling the binaries from the Maven staging repository.
Details of how to do this are also documented below.

== Prerequisites

You will also require the following commands/tools:

* `bash` - to run shell script
* `curl` - to download the ZIP and ASC files
* `gpg` - to verify signatures
* `unzip` - to unzip the ZIP files
* JDK 17

* Apache Maven (`mvn`) 3.9.6+

== Verifying source artifacts

The easiest way to verify the source artifacts is to use a script that automates the steps.
For extra safety, run within a docker container as a clean room.
These same details should also be in the VOTE email:

* Start the docker container:
+
[source,bash,subs="attributes+"]
----
include::partial$verify-process-docker-container.adoc[]
----

* and then within the docker container, install prerqs and verify (update the envirnment variables as necessary):
+
[source,bash,subs="attributes+"]
----
include::partial$verify-process-docker-container-prep.adoc[]

include::partial$verify-process.adoc[]
----

The `verify-causeway-release.sh` script performs these steps:

* downloads artifacts (`.zip` file and `.asc` file) from the staging repository hosted on link:https://repository.apache.org[].

* verifies that the `.asc` signature is correct
+
in other words, to confirm that the release was created by an Apache Causeway committer

* builds the framework code from source

* downloads and builds the helloworld starter app (for the `jdo` branch and also for the `jpa` branch)

* ditto for the simpleapp starter app

Assuming this completes successfully, you can then test the starter applications:

* Test out helloworld (jdo) using:
+
[source,bash]
----
pushd causeway-app-helloworld-jdo
mvn spring-boot:run
popd
----

* Test out helloworld (jpa) using:
+
[source,bash]
----
pushd causeway-app-helloworld-jpa
mvn spring-boot:run
popd
----

* Test out simpleapp (jdo) using:
+
[source,bash]
----
pushd causeway-app-simpleapp-jdo
mvn -pl webapp spring-boot:run
popd
----

* Test out simpleapp (jpa) using:
+
[source,bash]
----
pushd causeway-app-simpleapp-jpa
mvn -pl webapp spring-boot:run
popd
----


You can if you wish perform some additional optional checks, listed xref:#optional-creadur-tools[below].
And/or, you can go ahead and xref:comguide:ROOT:verifying-releases.adoc#casting-a-vote[cast your vote].


== (Optional) Verify Website

The next version of the website can be found at link:https://causeway.staged.apache.org[].

[#optional-creadur-tools]
== (Optional) Creadur Tools

The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards.

The main release auditing tool, http://creadur.apache.org/rat[Apache RAT] is used in the xref:comguide:ROOT:cutting-a-release.adoc[release process].

Creadur's remaining tools - link:http://creadur.apache.org/tentacles/[Tentacles] and link:http://creadur.apache.org/whisker/[Whisker] - are to support the verification process.

For example, Tentacles generates a report called `archives.html`.
This lists all of the top-level binaires, their `LICENSE` and `NOTICE` files and any `LICENSE` and `NOTICE` files of any binaries they may contain.

Validation of the output at this point is all still manual.
Things to check include:

* any binaries that contain no LICENSE and NOTICE files
* any binaries that contain more than one LICENSE or NOTICE file

In this report, each binary will have three links listed after its name '(licenses, notices, contents)'

[#casting-a-vote]
== Casting a Vote

When you have made the above checks (and any other checks you think may be relevant), cast your vote by replying to the email thread on the mailing list.

If you are casting `-1`, please provide details of the problem(s) you have found.
