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/incubator-openwhisk-release.git


The following commit(s) were added to refs/heads/master by this push:
     new 607e1dc  Add the documentation to describe the manual mode of release 
(#42)
607e1dc is described below

commit 607e1dc4b763e448e95b421c60e94086705f5df0
Author: Vincent <s...@us.ibm.com>
AuthorDate: Tue Feb 13 15:08:55 2018 -0500

    Add the documentation to describe the manual mode of release (#42)
---
 README.md                        |  4 +++
 docs/package_artifacts.md        | 13 +++++++++
 docs/pick_up_source_code.md      | 59 ++++++++++++++++++++++++++++++++++++++++
 docs/prepare_release.md          |  7 +++++
 docs/prerequisites.md            | 33 ++++++++++++++++++++++
 docs/publish_apache_directory.md | 14 ++++++++++
 docs/push_stage_url.md           | 12 ++++++++
 docs/sign_artifacts.md           | 25 +++++++++++++++++
 docs/tutorial.md                 | 21 ++++++++++++++
 docs/upload_public_key.md        | 15 ++++++++++
 10 files changed, 203 insertions(+)

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).

-- 
To stop receiving notification emails like this one, please contact
mrutkow...@apache.org.

Reply via email to