This is an automated email from the ASF dual-hosted git repository.
mrutkowski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/openwhisk-release.git
The following commit(s) were added to refs/heads/master by this push:
new 79084ef Continue to refine release manager instructions (#380)
79084ef is described below
commit 79084efe2b09712191c89da01ae48c2e660dae74
Author: Matt Rutkowski <[email protected]>
AuthorDate: Tue Mar 16 10:27:14 2021 -0500
Continue to refine release manager instructions (#380)
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
* Continue to refine release manager instructions
---
docs/release_instructions.md | 98 +++++++++++++++++++++++++++++++++----
docs/release_manager_setup.md | 2 +-
docs/tag_release.md | 109 ++++++++++++------------------------------
3 files changed, 119 insertions(+), 90 deletions(-)
diff --git a/docs/release_instructions.md b/docs/release_instructions.md
index 42f70e9..1bf994d 100644
--- a/docs/release_instructions.md
+++ b/docs/release_instructions.md
@@ -217,7 +217,7 @@ Use the [gen-release-vote.py](../tools/gen-release-vote.py)
script to create the
This script accepts a [mailer configuration
file](https://github.com/apache/openwhisk-release/blob/master/tools/mail-config-template.yaml)
which you can use to also send the vote email directly to the mailing list.
_You should dry run this command with `-n` to sanity check the vote notice
before it is sent._
-```
+```sh
./gen-release-vote.py ../release-configs/<MY_RELEASE_CONFIG>.json -mc
<MY_MAILER_CONFIG>.yaml
```
@@ -246,10 +246,15 @@ If this is not true (e.g., multiple parallel release
votes), then the upload mus
```
Assuming the expected set of files were added, commit them:
-```
+
+```sh
cd ../stagingArea/svn_release && svn commit -m "Apache OpenWhisk X.Y.Z
release of <Component Description>"
```
+You can verify your commit to the Apache OpenWhisk official release folder:
+
+- https://dist.apache.org/repos/dist/release/openwhisk/
+
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.
```text
@@ -270,23 +275,96 @@ and add your release data (version and date) to the
database.
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
+### Tag GitHub repositories
-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.
+Each GitHub repository needs to be tagged.
+
+> **Note** Some 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 tag each released
project using the same hash values specified in the release configuration file
(i.e., `openwhisk-release/release-configs/<release config>.json`) and approved
by member email `[VOTE]`.
+
+Open a terminal, go the home directory of the OpenWhisk project to be released
and run the following commands:
+
+```sh
+git tag -s -a <tag> -m "OpenWhisk <project name> v<tag>" <commit hash>
+git push <remote_url_var> <tag>
+```
-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.
+- [*Optional*] It is good practice to sign release tags using your GPG key by
adding the `-s` flag which will use your system default key from your operating
system keychain.
+ - See [Signing tags using GPG keys](#signing-tags-using-gpg-keys) below.
+- Replace `<tag>` with the tag name for the release of the current project
(e.g., 1.1.0).
+- Update the commit message, `-m` to reflect the project name and version
which should match the release tag
+- Replace `<commit hash>` with the commit hash (ID) you designated for the
release of the current project. This can either be the full commit hash or the
first 8 letters of the hash (to assure unique lookup).
+- Replace `<remote_url_var>` to the remote repository label of the OpenWhisk
project which is typically set to `upstream` for a project Committer and maps
to the full GitHub URL (e.g., `[email protected]:apache/<project name>`)
+
+### Signing tags using GPG keys
+
+First [add your public GPG key to your GitHub
Settings](https://docs.github.com/en/github/authenticating-to-github/telling-git-about-your-signing-key)
and also [verify your key's associated `apache.org`
email](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/adding-an-email-address-to-your-github-account).
Then add it to your repository's local `git` configuration:
+
+```sh
+gpg --list-secret-keys --keyid-format LONG
+git config user.signingkey <your GPG key ID>
+```
+
+Assure your repository's local `git` email is set to your `apache.org` email
which matches your GPG key:
+
+```sh
+git config user.email <Apache username>@apache.org
+```
+
+You can verify your configuration by examining your local repository's
`.git/config` file either manually or with:
+
+```sh
+git config --list
+```
+
+#### Deleting a tag
+
+If a mistake is made, you can delete the undesired tags and start over:
+
+```sh
+git tag -d <tag>
+```
+
+Run the following command to remove a remote tag:
+
+```sh
+git push --delete <remote_url_var> <tag>
+```
+
+or try:
+
+```sh
+git push <remote_url_var> :refs/tags/<tag>
+```
+
+where `<remote_url_var>` is typically set to `upstream` for a project
Committer.
+
+> You can attempt to use the force `-f` flag if a normal `push` fails
+
+#### Syncing release tags
+
+If your fork's tags do not match those in the Apache project repository, you
can sync them much like rebasing:
+
+```sh
+git fetch --tags upstream
+git push -f --tags origin master
+```
+
+where `upstream` is the remote label for the Apache project repo. and `origin`
is the remote label for your fork.
+
+### Automated build of tagged binary release artifacts
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.
+There are some slightly dated, but much more detailed comments on [Verifying
release binaries](tag_release.md#verifying-release-binaries) 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.
-Update the project's:
-
-- `CHANGELOG` or `RELEASENOTES` to include the release versions, description
and a list of all commits since the last release. Copy that information into
the release description.
+- If you have not already done so prior to voting on the release, update the
project's `CHANGELOG` or `RELEASENOTES` to include the release versions,
description and a list of all commits since the last release.
+- Copy that same information information into the release description in
GitHub.
### Dockerhub updates
@@ -296,7 +374,7 @@ If the components you released build docker images, then
you should build the do
Push the new images to the [openwhisk
dockerhub](https://hub.docker.com/u/openwhisk) using the whiskbot dockerhub id,
and update the `latest` tag to point to the new images.
-### Rippling changes for openwhisk-runtime-- releases
+### Rippling changes for `openwhisk-runtime-xxx` releases
If you are releasing a new version of an openwhisk runtime (e.g.,
`openwhisk-runtime-python`), then once the updated images are available on
[dockerhub](https://hub.docker.com/u/openwhisk) you should submit a PR to
openwhisk-deploy-kube to update the docker imageTags in that project's
`helm/openwhisk/runtimes.json`.
diff --git a/docs/release_manager_setup.md b/docs/release_manager_setup.md
index dea6c16..8256776 100644
--- a/docs/release_manager_setup.md
+++ b/docs/release_manager_setup.md
@@ -124,7 +124,7 @@ Append both your key's signature and ASCII-armored public
key to the KEYS file:
(gpg --list-sigs <your name> && gpg --armor --export <your name>) >> KEYS
```
-> *In recent releases of GnuPG, the- `gpg` and `gpg2` *commands utilize the
same code and should be viewed as equivalent in any legacy instructions.*
+> *In recent releases of GnuPG, the `gpg` and `gpg2` commands utilize the same
code and should be viewed as equivalent in any legacy instructions.*
#### PGPK Example
diff --git a/docs/tag_release.md b/docs/tag_release.md
index 306eaf4..4e720b5 100644
--- a/docs/tag_release.md
+++ b/docs/tag_release.md
@@ -17,66 +17,22 @@
#
-->
-# Tag the commit IDs in the Github repository for the project
-
-All the hash values are available in the configuration file config.json for
each OpenWhisk project. We need to tag them
-with the name of the release, e.g: \<version\>-\<pre_release_version\>. Since
different OpenWhisk projects may have different
-naming conventions to tag their commits, this step is currently done in a
manual way, but it is very important for the
-release process.
-
-Open a terminal, go the home directory of the OpenWhisk project to be released
and run the following commands to tag a
-certain commit:
-```
-git tag <tag> <commit ID>
-git push <remote_url_var> <tag>
-```
-
-Replace the notation \<tag\> with the tag name for the release of the current
project. As a release manager, you should be
-familiar with the tag's naming convention for the module to be released. Take
the Nodejs runtime as example, you need to use
-the tag like \<node kind\>@\<version\>-\<pre_release_version\>. The notation
\<node kind\> should be 8 or 10 for a specific
-Nodejs version, but for OpenWhisk, you can directly use
\<version\>-\<pre_release_version\> as the tag. Please make sure
-you use the correct format of tags, when you release OpenWhisk modules. If you
are not sure how to name the tag, ask the
-OpenWhisk community.
-
-Replace the notation \<commit ID\> with the commit ID you designated for the
release of the current project. For \<commit ID\>,
-you can either choose the full commit ID or the first 7 letters.
-
-Replace the notation \<remote_url_var\> with the local variable linking to the
remote repository of the OpenWhisk project.
-Take OpenWhisk module as an example, we usually link the variable "origin" to
the fork we are working on, and the
-variable "upstream" to the remote repository of official OpenWhisk project. To
push a tag, we run "git push remote \<tag\>".
-
-To add a variable, you can run the following command as an example:
-```
-git remote add <remote_url_var> <full_remote_url>
-```
-
-To change an existing variable, you can run the following command as an
example:
-```
-git remote set-url <remote_url_var> <full_remote_url>
-```
-
-If you are releasing OpenWhisk, the \<full_remote_url\> will be
"[email protected]:apache/openwhisk.git" or
-"https://github.com/apache/openwhisk.git";.
-
-In case of making mistakes, you may need to remove tags. You can run the
following command to remove a local tag:
-```
-git tag -d <tag>
-```
-
-Run the following command to remove a remote tag:
-```
-git push --delete <remote_url_var> <tag>
-```
-
-### Be aware of Travis builds that failed for tags
-
-After you push a tag to a Github repository for OpenWhisk project, it will
kick off a Travis build job, which probably will
-push the built docker images for that project into [Docker
Hub](https://hub.docker.com/u/openwhisk/). If the Travis job fails,
-we will fail to push the docker images, which lead to image inconsistency for
our release. When you push a release tag into
-each OpenWhisk project, don't forget to verify whether the Travis build
succeed or not.
-
-If the Travis job succeeds, you are all set for this step; if the Travis job
fails, you need to find out the reason,
-why it has failed. Empirically, it fails due to that you pushed a tag, not
compliant with naming convention for that project.
+## Verifying release binaries
+
+### Verify Travis builds succeed after tagging
+
+After you push a tag to a Github repository for OpenWhisk project, it will
kick off a Travis build job, which probably will push the built docker images
for that project into [Docker Hub](https://hub.docker.com/u/openwhisk/).
+
+> **Important!** Don't forget to verify whether the Travis build succeed or
not.
+
+- **If the Travis job fails**, we will fail to push the docker images, which
lead to image inconsistency for our release.
+
+ You need to find out the reason, why it has failed. Empirically, it fails
due to that you pushed a tag, not compliant with naming convention for that
project.
+
+- **If the Travis job succeeds**, you are all set for this step.
+
+#### Example: Runtime Go
+
Let's take the Go runtime as an example, if you name the tag after
"[email protected]", the Travis build will fail,
like the error result
[here](https://travis-ci.org/apache/openwhisk-runtime-go/builds/532326848). The
correct tag for Go runtime in this case is like "[email protected]",
and the successful
build is located
[here](https://travis-ci.org/apache/openwhisk-runtime-go/builds/533325334).
@@ -85,29 +41,24 @@ Another reason that the Travis build fails can be there is
really a bug with the
the tag you have pushed in the Github repository, but log this issue as well.
One way to compensate is to run the "docker push"
manually on your local machine to upload the image into Docker Hub. Here are
the steps you need to follow for this situation:
-1. Visit the private SVN repository to access the credentials for Docker Hub
+1. Visit the private SVN repository to access the credentials for Docker Hub.
If you are a PMC member, your credentials with Apache should give you the
access to the [private SVN
repository](https://svn.apache.org/repos/private/pmc/openwhisk/accounts).
-After you login with your credentials, open the file called dockerhub.txt, and
you will see the username and password to
-push your local docker images. DON'T misuse it.
+After you login with your credentials, open the file called `dockerhub.txt`,
and you will see the username and password to push your local docker images.
**DON'T misuse it.**
+
+1. On your local machine, run the command as below to login the Docker Hub:
-2. On your local machine, run the command as below to login the Docker Hub:
+ ```sh
+ docker login --username <openwhisk_username>
+ ```
-```shell
-docker login --username <openwhisk_username>
-```
+ The argument \<openwhisk_username\> is the username you retrieve in the
file dockerhub.txt. This command asks you to enter the password, we can get in
the file dockerhub.txt as well.
-The argument \<openwhisk_username\> is the username you retrieve in the file
dockerhub.txt. This command asks you to enter
-the password, we can get in the file dockerhub.txt as well.
+1. Build the docker image locally with correct version number and push it into
the Docker hub. You need to go to the home directory of the specific OpenWhisk
project, and run the following command:
-3. Build the docker image locally with correct version number and push it into
the Docker hub. You need to
-go to the home directory of the specific OpenWhisk project, and run the
following command:
+ ```sh
+ ./gradlew :core:<runtime_kind>:distDocker -PdockerRegistry=docker.io
-PdockerImagePrefix=openwhisk -PdockerImageTag=<tag>
+ ```
-```shell
-./gradlew :core:<runtime_kind>:distDocker -PdockerRegistry=docker.io
-PdockerImagePrefix=openwhisk -PdockerImageTag=<tag>
-```
+ The argument \<runtime_kind\> is the folder name for each version of the
runtime. You can find the name by checking what are under the folder core. For
example, your want to find the runtime kind for the runtime Ruby, there are
`ruby2.5Action` and `ruby2.6ActionLoop` under the [core
folder](https://github.com/apache/openwhisk-runtime-ruby/tree/master/core).
-The argument \<runtime_kind\> is the folder name for each version of the
runtime. You can find the name by checking what
-are under the folder core. For example, your want to find the runtime kind for
the runtime Ruby, there are ruby2.5Action
-and ruby2.6ActionLoop under the [core
folder](https://github.com/apache/openwhisk-runtime-ruby/tree/master/core). The
candidates
-for \<runtime_kind\> will be ruby2.5Action or ruby2.6ActionLoop. The argument
\<tag\> is usually \<version\>-\<pre_release_version\>,
-the real full version we specify for each release.
+ The candidates for \<runtime_kind\> will be `ruby2.5Action` or
`ruby2.6ActionLoop`. The argument \<tag\> is usually
\<version\>-\<pre_release_version\>, the real full version we specify for each
release.
