docs/release_instructions.md

<!--
#
# 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.
#
-->

# Instructions for Release Managers

## Background Information

If you are acting as a Release Manager, you should be familiar with
the Apache Software Foundation's (ASF)
[Release Creation Process](http://www.apache.org/dev/release-publishing.html) and
[Release Policy](http://www.apache.org/legal/release-policy.html).
The detailed instructions and scripts we provide for Release Managers
are designed to implement the ASF's policies and procedures in the
specific context of the OpenWhisk project. However, it is still
essential that each Release Manager understands the rationale underlying
the steps they are executing.

### Licensing requirements

All released source code has to be compliant with Apache Licensing
Policy. In part this is done by adding the LICENSE file and NOTICE file
to each git repository and by adding Licensing headers to each source code
file.  Please see [License Compliance](license_compliance.md) for
detailed information on Apache OpenWhisk project policies, rules and
guidelines.

### Artifact requirements

Artifacts for project repository source code and any compiled binaries
are packaged separately with each artifact being signed
cryptographically.

### Release Approval

All Releases must be formally approved via a PMC vote on the dev list.
A successful release vote must have a minimum of three positive binding
votes and more positive than negative binding votes MUST be cast.

### Release distribution requirements

All release artifacts must be uploaded to project’s designated subdirectory in the Apache distribution channel ([https://dist.apache.org/repos/dist/](https://dist.apache.org/repos/dist/)).

Specifically, the Apache OpenWhisk project has a subdirectory to publish both candidate (staged) releases:
[https://dist.apache.org/repos/dist/dev/openwhisk/](https://dist.apache.org/repos/dist/dev/openwhisk/)
and approved releases:
[https://dist.apache.org/repos/dist/release/openwhisk/](https://dist.apache.org/repos/dist/release/openwhisk/).

Release announcements should not directly refer to the main Apache dist server for mirrored artifacts (the sources.tar.gz files). Instead they should refer to the OpenWhisk project download page [https://apache.openwhisk.org/downloads](https://openwhisk.apache.org/downloads) which is configured to redirect download requests to Apache dist mirrors or otherwise incorporate a mirroring enabled URL.

# Step-by-Step Instructions for the Release Process

### Preparing to Make a Release

Before creating release artifacts, the Release Manager should initiate a community discussion to confirm that we are ready to release the component(s). It is also good practice to do a quick check of the repositories to confirm they are release-ready to reduce the odds of needing multiple release candidates.
  1. Start a [DISCUSS] thread on the dev list proposing the release.  Allow at least 24 hours for feedback.
  2. Make sure all unit and integration tests are passing in the repositories that are being released. Check the [project status list](../README.md#project-status).
  3. If a component being released includes a changelog or release notes file, make sure they are up-to-date.

### Defining the Release Contents

The contents of a release are defined by a JSON configuration file.
To create one for your release, make a copy of [config_template.json](../tools/config_template.json)
and edit to provide the version information, list of repositories, and details for each repository.
After creating your config, commit it to [../release-configs](../release-configs) to
provide historical documentation of project releases.

```
{
  "versioning": {
    "version": "X.Y.Z",
    "pre_release_version": "rc1"
  },
  "RepoList": [
    "openwhisk-repo-name-one",
    "openwhisk-repo-name-two"
  ],
  "openwhisk_repo_name_one": {
    "name": "OpenWhisk Repo Name",
    "hash": "<GIT COMMIT HASH>",
    "repository": "https://github.com/apache/openwhisk-<REPO-NAME-ONE>.git",
    "branch": "master"
  },
  "openwhisk_repo_name_two": {
    "name": "OpenWhisk Repo Two",
    "hash": "<GIT COMMIT HASH>",
    "repository": "https://github.com/apache/openwhisk-<REPO-NAME-TWO>.git",
    "branch": "master"
  }
}
```
  - **versioning**: Defines the release version and the release candidate number.
  - **RepoList**: Defines the list of OpenWhisk repositories being released.
  - For every repository in `RepoList`, we name-mangle it to convert `-` into `_` and use the
    mangled name as a key whose value is an object that defines
     - name: User level name of the component
     - hash: git commit hash being released
     - repository: URL of the repository
     - branch: git branch being released

### Create Release Candidates

From the [tools directory](../tools), execute the script
[build_release.sh](../tools/build_release.sh)
providing the config.json file as an argument.
Using ../stagingArea as scratch space, this script will clone the
source repositories, package them into compressed tarballs, and create
the checksum and detached PGP signature files.
```
./build_release.sh ../release-configs/<MY_RELEASE_CONFIG>.json
```

Next, verify the release artifacts by running [local_verify.sh](../tools/local_verify.sh). This
script will run rcverify.sh against your local artifacts.
```
./local_verify.sh ../release-configs/<MY_RELEASE_CONFIG>.json
```

TODO:  We should also run Apache Rat as part of local_verify.sh; for now it is
a recommended best practice to run Apache Rat by hand on each of your .tar.gz files.

If the release candidates pass all checks, commit them to the staging svn:
```
./upload_to_staging.sh ../release-configs/<MY_RELEASE_CONFIG>.json
```

### Initiate a Release Vote

Initiate a release vote on the dev list.
Use the [gen-release-vote.py](../tools/gen-release-vote.py)
script to create the body of the voting email.

### Report Vote Result

When the vote can be closed (at least 72 hours and minimum number of
binding votes cast), the Release Manager will respond to the voting
thread modifying the subject to start with `[RESULT][VOTE]...`
announcing the result of the vote. If the vote has sufficient -1 votes
cast, the Release Manager may declare that the vote has failed without
waiting the full 72 hours.

If the vote is successful, the Release Manager proceeds with
publishing the release and cleaning up as described below.

It the vote is unsuccessful, correct whatever issues were raised and
restart the process with new candidate releases.  Update your
`config.json` file by incrementing the `rc` number and changing git
hashes.

### Publishing a Successful Release to Apache Dist Servers

After a successful vote, the release manager will commit the artifacts
being released to the `openwhisk` subdir of the Apache dist svn.

The [`upload_to_dist.sh`](../tools/upload_to_dist.sh) script automates the copy & svn add operations, but it
assumes that every file found in the release candidate subdir should be released.
If this is not true (e.g., multiple parallel release votes), then the upload
must be performed manually.
```
./upload_to_dist.sh ../release-configs/<MY_RELEASE_CONFIG>.json
```

Assuming the expected set of files were added, commit them:
```
cd ../stagingArea/svn_release && svn commit -m  "Apache OpenWhisk X.Y.Z release of <Component Description>"
```

Relatively soon after doing the svn commit, you should receive an email like
the one shown below from reporter.apache.org asking you to add release data
to its database information.
```
Hi,
This is an automated email from reporter.apache.org.
I see that you just pushed something to our release repository for the 'openwhisk' project
in the following commit:

r35971 at 2019-09-23 16:07:53 +0000 (Mon, 23 Sep 2019)
Apache OpenWhisk CLI Group v1.0.0

If you are a PMC member of this project, we ask that you log on to:
<URL ELIDED>
and add your release data (version and date) to the database.

...elided rest of email...
```
Please follow the link and perform the update; this information is
quite useful for drafting our periodic reports to the ASF Board.

### Tag GitHub repos

Each GitHub repository needs to be tagged.  Unfortunately, the naming conventions for
tagging vary across the OpenWhisk project repositories and therefore we have not
yet attempted to automate this step.

For each released repository, the Release Manager should examine the existing set of
tags (`git tag`) and then add a new tag following the same convention using the
git commit hash from <MY_RELEASE_CONFIG>.json.  After tagging a repo, push the tag.

Many of the GitHub repositories are configured to build binary artifacts in response
to new tags being committed.  Monitor the build process and ensure that all expected
artifacts are created for each tag you commit.

There are some slightly outdated, but much more detailed comments
on [release tagging](tag_release.md) available if you need a reminder
of the git commands to use.

### Create GitHub releases

After pushing the tags, you should go to the GitHub Releases for
each released project and "Draft a new release" using the tag you just
pushed. If the project contains a CHANGELOG or RELEASENOTES, copy that
information into the release description.

### Dockerhub updates

If the components you released build docker images, then you should
build the docker images locally, tag them with the release version
(following the naming scheme for the repo), push the new images to
dockerhub using the whiskbot dockerhub id, and update the `latest`
tag to point to the new images.

If you have published new images to dockerhub, submit PRs to
[openwhisk-deploy-kube](https://github.com/apache/openwhisk-deploy-kube) and [openwhisk-devtools (docker-compose)](https://github.com/apache/openwhisk-devtools) to use the new images.

### Homebrew

If you released a new version of openwhisk-cli, then submit a PR
to Homebrew to publish the new cli version.

### Update Downloads Page

Submit a PR to [openwhisk-website](https://github.com/apache/openwhisk-website) to update the Downloads page to
refer to the newly released versions.

### Announcing the Release

For all normal releases you should wait at least 24 hours before
announcing the release to allow time for Apache Dist mirrors to
be updated with the newly released artifacts.  You must also wait
until the PR to update the website has been merged and the
change appears on the website (successful Jenkins job to rebuild website).

When announcing a release, you must use the URL of the OpenWhisk Downloads
page (or some other URL that supports mirroring).  Do not include a direct
link to the dist.apache.org svn server.

Releases should always be announced to dev@openwhisk.apache.org.
Releases can optionally be announced to announce@apache.org at the discretion
of the release manager.

### Post-release cleanup

1. Remove the release candidate files from the staging svn.
2. If there is a prior release, remove it from the release svn
(all releases are automatically archived, removing an old release
from dist does not remove it from the archive).