mrutkows closed pull request #42: Add the documentation to describe the manual
mode of release
URL: https://github.com/apache/incubator-openwhisk-release/pull/42
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/README.md b/README.md
index 0471157..6f53514 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,10 @@ We use Travis CI as the automated integration build tool to
streamline the relea
applied to build different jobs, which are able to run either in sequential or
parallel. Artifacts can be shared across
different jobs by using cache in Travis, as different jobs run on different
virtual machines.
+# Instruction to use OpenWhisk Release
+
+As a release manger of OpenWhisk, please visit [OpenWhisk Release
tutorial](docs/tutorial.md).
+
# How to release an Apache project
## Release Approval
diff --git a/docs/package_artifacts.md b/docs/package_artifacts.md
new file mode 100644
index 0000000..61c8f02
--- /dev/null
+++ b/docs/package_artifacts.md
@@ -0,0 +1,13 @@
+# Making the release artifacts
+
+The artifacts to be made in this step consists of the source code packages,
binary packages and docker image packages.
+As the deliverable of the [first
phase](general_spec.md#different-phases-of-implementations), we currently only
build the
+source code packages. Binary and docker image are on our future agenda.
+
+After downloading the source code, we can run the following script under
_tools_ to generate the artifacts for each OpenWhisk project:
+```
+$ ./package_source_code.sh <WORK_DIR>
+```
+The <WORK_DIR> should be the same one used to download the source code. This
script will create a source code package file
+of source code suffixed with tar.gz for each project, under
<WORK_DIR>/openwhisk_sources/openwhisk/openwhisk-\<major\>-\<minor\>.
+The keys major and minor are defined in _config.json_.
diff --git a/docs/pick_up_source_code.md b/docs/pick_up_source_code.md
new file mode 100644
index 0000000..47ee8b7
--- /dev/null
+++ b/docs/pick_up_source_code.md
@@ -0,0 +1,59 @@
+# Picking up source code
+
+## Edit the configuration file
+
+The only file that a release manager needs to edit is the JSON-format
configuration file named _config.json_ under the
+folder _tools_. You can specify the the staging url, release url, the list of
projects to be release, the repository url,
+branch name, and hash value of the source code for each project, etc.
+
+Template of [_config.json_](../tools/config.json):
+
+```
+{
+ "stage_url": "https://dist.apache.org/repos/dist/dev/incubator/openwhisk";,
+ "release_url":
"https://dist.apache.org/repos/dist/release/incubator/openwhisk";,
+ "version": {
+ "major": "incubator",
+ "minor": "rc1"
+ },
+ "RepoList": [
+ "incubator-openwhisk",
+ "incubator-openwhisk-wskdeploy",
+ "incubator-openwhisk-cli"
+ ],
+ "incubator_openwhisk": {
+ "hash": "a891e06",
+ "repository": "https://github.com/apache/incubator-openwhisk.git";,
+ "branch": "master"
+ },
+ "incubator_openwhisk_wskdeploy": {
+ "hash": "1425456",
+ "repository":
"https://github.com/apache/incubator-openwhisk-wskdeploy.git";,
+ "branch": "master"
+ },
+ "incubator_openwhisk_cli": {
+ "hash": "1448d31",
+ "repository": "https://github.com/apache/incubator-openwhisk-cli.git";,
+ "branch": "master"
+ }
+}
+```
+ - **stage_url**: the field to specify the staging url, where to upload the
artifacts.
+ - **release_url**: the field to specify the Apache release directory url,
where to finally release the artifacts.
+ - **version**: the key to define the release name, with both a major and a
minor name.
+ - **RepoList**: the key to define the list of OpenWhisk projects to be
released. Based on this key, we need to add other
+ keys below with each of them matching each project name. For example, we
define three projects in _RepoList_, so we
+ have three other keys below to match each project.
+ - **<project_name>**: the key used to match one OpenWhisk project. If there
is any hyphen(-) sign in the project name, we need
+ to convert it into underscore(_). Hash key defines the hash value,
repository defines the url of the project repository,
+ and branch defines the branch name in the project repository. We can
precisely locate a version of the source code to
+ pick up for the release.
+
+## Download the source code to a local directory
+
+Run the following script to download source code based on the configuration in
_config.json_:
+```
+$ ./download_source_code.sh <WORK_DIR>
+```
+You may specify where to download all the source code with <WORK_DIR>. If you
specify the <WORK_DIR> here, you need to
+specify the same value as well to the sequential scripts as well. It will take
$HOME by default.
diff --git a/docs/prepare_release.md b/docs/prepare_release.md
new file mode 100644
index 0000000..63bfb64
--- /dev/null
+++ b/docs/prepare_release.md
@@ -0,0 +1,7 @@
+# Prepare OpenWhisk projects for a release
+
+ 1. Make sure all unit and integration tests are passing in all the projects
to be release. Check the [project
list](general_spec.md#list-of-openwhisk-repositories-to-be-released).
+ 2. Make sure the license file LICENSE.txt and the notice file NOTICE.txt
exist in each project repository. The license
+ file contains the Apache V2.0 license and the notice file includes the
dependencies.
+ 3. Update the release notes. (It is still to be determined where to publish
the release notes)
+ 4. Update the changelog file CHANGELOG.txt for each project, including the
new commits based on the previous release.
diff --git a/docs/prerequisites.md b/docs/prerequisites.md
new file mode 100644
index 0000000..aa3312f
--- /dev/null
+++ b/docs/prerequisites.md
@@ -0,0 +1,33 @@
+# Release Prerequisites
+
+## Operating Systems
+
+This project is only supported under Mac or Ununtu operating system.
+
+## Software packages
+
+The following software packages are required for your operating system.
+
+ - git and svn
+ - jq
+ - gpg or gnupg and expect
+
+## Download the source code
+
+Open a terminal, go to the directory where you save the source code, and run
+```
+$ git clone https://github.com/apache/incubator-openwhisk-release.git
+```
+
+## Install the dependencies
+
+Normally, Mac or Ubuntu will have some the packages installed by default.
Suppose _$OPENWHISK_RELEASE_ is the home directory
+of openwhisk release on your local machine. You can run the script
_install_dependencies.sh_ under the folder _tools_
+to install the software packages:
+```
+$ cd $OPENWHISK_RELEASE/tools
+$ ./install_dependencies.sh
+```
+
+For some old versions of Ubuntu, you probably need to run _sudo apt-get
update_ before running the script to install
+dependencies.
diff --git a/docs/publish_apache_directory.md b/docs/publish_apache_directory.md
new file mode 100644
index 0000000..9a4e5a3
--- /dev/null
+++ b/docs/publish_apache_directory.md
@@ -0,0 +1,14 @@
+# Publish the release artifacts to Apache release directory
+
+## Move the artifacts from the staging directory to the Apache release
directory
+
+We shall not proceed this step unless we have reached the consent from the
community to promote a release. Run the following
+script under _tools_ to accomplish this task:
+```
+$ ./move_stage_to_release.sh
+```
+
+## Tag the release in git
+
+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: \<major\>-\<minor\>.
diff --git a/docs/push_stage_url.md b/docs/push_stage_url.md
new file mode 100644
index 0000000..ddee6c3
--- /dev/null
+++ b/docs/push_stage_url.md
@@ -0,0 +1,12 @@
+# Publish the release artifacts to the staging directory
+
+After the artifacts are generated and signed, you can run the following script
under the folder _tools_, to upload them
+into the staging directory:
+
+```
+$ ./upload_artifacts.sh <WORK_DIR>
+```
+
+The <WORK_DIR> should be the same one used to download the source code. This
script will create a remote directory named
+openwhisk-\<major\>-\<minor\> under the staging directory, and push all the
files available locally under openwhisk-\<major\>-\<minor\>
+upstream. It will overwrite the old files or directories, if the directory
openwhisk-\<major\>-\<minor\> is available as a svn folder.
diff --git a/docs/sign_artifacts.md b/docs/sign_artifacts.md
new file mode 100644
index 0000000..c04fa88
--- /dev/null
+++ b/docs/sign_artifacts.md
@@ -0,0 +1,25 @@
+# Sign the artifacts
+
+Each package needs to be accompanied by cryptographic signatures according to
Apache release policy.
+
+## Generate the PGP key pair
+
+You can either follow the [online PGP
instruction](https://support.symantec.com/en_US/article.HOWTO41935.html) to
generate the PGP key for your environment, or use our script to
+generate for you. First, you need to config _pgp_key_gen.conf_ under the
folder _tools_. Make sure you have the proper
+Name-Real, Name-Comment, Name-Email, and Passphrase for your key. You do not
need to change Key-Type, Key-Length, and
+Expire-Date. Run the following script under the folder _tools_:
+
+```
+$ ./generate_pgp_key.sh
+```
+
+## Sign the artifacts:
+
+All the artifacts can be signed by running the following script under _tools_:
+
+```
+$ ./sign_artifacts.sh <WORK_DIR>
+```
+
+The <WORK_DIR> should be the same one used to download the source code. This
script generates a file of the MD5 checksum suffixed with .md5,
+a file of the SHA512 checksum suffixed with .sha512, and a signature file
suffixed with .asc for each package.
diff --git a/docs/tutorial.md b/docs/tutorial.md
new file mode 100644
index 0000000..70c692b
--- /dev/null
+++ b/docs/tutorial.md
@@ -0,0 +1,21 @@
+# Release Manager Tutorial
+
+This project offers the release manager of OpenWhisk two modes to release
OpenWhisk projects: manual mode and automated mode.
+Manual mode makes sure that the release manager can download the source code
of this repository, and go through the release
+process by running scripts sequentially on a local machine, to push the
artifacts into the staging directory and eventually
+move them into the Apache release directory. Automated mode provides the
release manager another option to walk through the
+Apache release process by kicking off the Travis job to run the scripts. A
release manager can choose either way to publish
+the artifacts in the staging directory and the Apache release directory.
+
+## Manual mode of Release Process
+ 1. [Preparing for a release](prepare_release.md) - how to prepare OpenWhisk
projects for a release
+ 2. [Prerequisites](prerequisites.md) - steps that release manager needs to
do before a release
+ 3. [Picking up the source code](pick_up_source_code.md) - determine the
branch and hash value for each OpenWhisk project to release
+ 4. [Making the release artifacts](package_artifacts.md)
+ 5. [Signing the release artifacts](sign_artifacts.md)
+ 6. [Uploading public PGP key](upload_public_key.md)
+ 7. [Publish the release artifacts to the staging
directory](push_stage_url.md)
+ 8. Vote on the d...@openwhisk.apache.org list
+ 9. If the vote fails - configure the file config.json and resume from step 3
+ 10. [Publish the release artifacts to Apache release
directory](publish_apache_directory.md)
+ 11. Announce the release
diff --git a/docs/upload_public_key.md b/docs/upload_public_key.md
new file mode 100644
index 0000000..24485e6
--- /dev/null
+++ b/docs/upload_public_key.md
@@ -0,0 +1,15 @@
+# Upload the public PGP key
+
+The public PGP key file is named _KEYS_ available under the [staging
directory](https://dist.apache.org/repos/dist/dev/incubator/openwhisk/). If you
generate a new key to
+sign the artifacts, you need to update the file of public key in the staging
directory for further use to verify the
+artifacts. Checkout the [staging
directory](https://dist.apache.org/repos/dist/dev/incubator/openwhisk/) via
subversion,
+modify the file KEYS by appending your local public key, and commit it back to
the staging directory.
+
+You can export your public PGP key by running the following command:
+
+```
+$ pgp --export <key_id>
+```
+
+The parameter <key_id> can be either the key id or the email address you used
to generate the key. For detailed information
+on PGP keys, please visit [how to create and manage PGP
keys](https://support.symantec.com/en_US/article.HOWTO41935.html).
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
