You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@openwhisk.apache.org by GitBox <gi...@apache.org> on 2018/02/13 20:08:59 UTC
[GitHub] mrutkows closed pull request #42: Add the documentation to describe the manual mode of release
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 dev@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:
users@infra.apache.org
With regards,
Apache Git Services