This is an automated email from the ASF dual-hosted git repository.
erans pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-numbers.git
The following commit(s) were added to refs/heads/master by this push:
new 28856b1 Avoid duplicate and outdated info (release howto).
28856b1 is described below
commit 28856b1193b0e5bb6b61cdb36a53e7435a420f0a
Author: Gilles Sadowski <gil...@harfang.homelinux.org>
AuthorDate: Wed Nov 6 17:20:48 2019 +0100
Avoid duplicate and outdated info (release howto).
---
doc/release/release.howto.txt | 625 +-----------------------------------------
1 file changed, 3 insertions(+), 622 deletions(-)
diff --git a/doc/release/release.howto.txt b/doc/release/release.howto.txt
index be4c09f..1d407f6 100644
--- a/doc/release/release.howto.txt
+++ b/doc/release/release.howto.txt
@@ -14,625 +14,6 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-This document is meant as a step-by-step recipe to achieve the release of
-the Commons Numbers component. Note that more general instructions valid
-for all components, including [rng], are available on the Apache Commons
-main site: at "http://commons.apache.org/releases/prepare.html"; and
-"http://commons.apache.org/releases/release.html";.
-
-The files "settings-security.xml" and "settings.xml" are minimal examples
-of files used by maven to pick up authentication credentials needed to
-connect to remote servers and to cryptographically sign the artifacts.
-
-Release preparation is done on the release manager local host in a branch.
-As branches deletion is now forbidden at Apache, we will use a specific
-release branch for every version.
-The branch will be simply named X.Y-release, with X.Y being the version number.
-The branch will be used to store the release specific parts (i.e. the pom
changes with
-the version number, the release date in the site and so on). Everything else
and in
-particular code change that will remain in the component after the release
must be
-committed to the master branch (or version branch). The release candidate
branch will
-be created from master or version branch at the start of each new candidate for
-this particular release. Once the release is done, the branch will be merged
back to
-master, but it will never be deleted so release history will be preserved.
-
-The example below show a typical workflow. Just after commit A in the master
branch, the
-X.Y-release branch is created starting from master. This is shown by the 'b'
in the
-second line. Then release specific commits are made on the pom and a few other
-files, leading to a commit which will be tagged as RC1. This release candidate
fails, and
-a few corrections need to be made on master, corresponding to commits B and C.
Then the
-X.Y-release branch is synchronized by running a 'git merge' command on the
branch.
-This is shown by the 'm' in the second line. A new commit is tagged as RC2.
This second
-release candidate also fails, and a new correction is made on master branch, a
new merge
-is done on the X.Y-release branch, a new commit is tagged and a third release
candidate is
-create, which succeeds. Then a final tag will be added on the final commit of
this branch
-showing the status as released. Then the files are cleaned to prepare for next
version
-(pom getting again a SNAPSHOT suffix, changes.xml getting a new placeholder
for changes)
-and the cleaned branch is merged back to master. Once the X.Y-release branch
has been merged,
-it is kept for history. The release for next version will use another specific
branch.
-
-
- ----A-------> B --> C---------->
D--------------------------------------m----> <- master branch
- \ \ \ /
- b---> RC1 ------m---> RC2 ---m---> RC3/final release --> cleaning --X
<- X.Y-release branch
-
-This process allows:
-
- - to never commit release candidate specific changes to the master
- branch (so the pom on master always holds a SNAPSHOT version),
- - to preserve future reference to the release
- - to allow parallel work on master during the release
- - if necessary to have multiple release managers or help on the
- release as the X.Y-release branch is shared
-
-
-(0)
-Preliminary checks:
- * All Java files must contain a license header. The "RAT" maven plugin will
- generate a report indicating for which files the license is missing.
- * For a "minor" release, the library must be backward-compatible. Check all
- the errors reported by the "Clirr" plugin.
- * Clear all "CheckStyle" warnings.
- * Make sure that the construct reported by "FindBugs" are intentional.
- * Mark all fixed issues as such in the bug-tracking system, and add a
- corresponding entry in "src/changes/changes.xml".
-
-
-(1)
-As an optional step, you can test that everything works locally, i.e.
-that the build process can create all the necessary artifacts.
-
- (1a)
- The command
-
- $ mvn clean deploy -Prelease -Ptest-deploy
-
- should create the artifacts in the "target/deploy" directory.
-
- At some point when processing the above command, the GPG passphrase will be
- requested; to avoid problems, the "gpg2" executable should be specified in
- the "settings.xml" file (see below).
-
- (1b)
- When the above works, you can test the creation of the full distribution
- files with the following commands:
-
- $ ( cd dist-archive && mvn assembly:single )
-
- The "dist-archive/target" directory will then contain those files:
- commons-numbers-1.0-SNAPSHOT-bin.tar.gz
- commons-numbers-1.0-SNAPSHOT-bin.zip
- commons-numbers-1.0-SNAPSHOT-src.tar.gz
- commons-numbers-1.0-SNAPSHOT-src.zip
-
-
-(2)
-At this point, you will work mainly on the X.Y-release branch.
-
-If the X.Y-release branch does not exist because it is the first release
-candidate, create it locally starting from the master branch or the version
-branch and push it to Apache repository (assuming it is called origin),
-remembering the binding between the local and remote origin branches:
-
- $ git branch 1.0-release
- $ git push -u origin 1.0-release
-
-
-(3)
-Switch to the release branch:
-
- $ git checkout 1.0-release
-
-
-(4)
-If there have been changes committed in the master branch or the version
-branch since the creation of the release branch, there are two cases:
-
- (4a)
- if all these changes must be included in version 1.0, merge "master"
- or the version branch into "1.0-release":
-
- $ git merge master
-
- or, if the version branch is called "NUMBERS_1_X"
-
- $ git merge NUMBERS_1_X
-
- (4b)
- if only part of these changes must be included in version 1.0,
- cherry-pick the required commits into the "1.0-release" branch:
-
- $ git cherry-pick commit-SHA
-
-
-(5)
-Update the release specific files, checking you are really working on the
-1.0-release branch and *not* on the master branch.
-
-In particular:
- * Update and commit the "src/site/site.xml" file to contain the information
- about the API docs of the new release.
- * Estimate a release date (taking into account the release vote delay) and
- insert it in the "src/changes/changes.xml" file.
- * Update the "pom.xml" to contain the final version number and not a SNAPSHOT:
- Assuming that the release version will be "1.0", modify the "<version>" tag
to
- read:
-
- <version>1.0</version>
-
- Modify the section of "<properties>" that also refers to version numbers.
- You should uncomment the "<commons.rc.version>" line and indicate the
- appropriate numbering of the release candidate: This refers to how many
- times you will need to repeat this whole release process until it is
- accepted (by a vote):
-
- <properties>
- <!-- ... -->
- <commons.release.version>1.0</commons.release.version>
- <commons.rc.version>RC1</commons.rc.version>
- <!-- ... -->
- </properties>
-
-
-(6)
-The "download" page template is located at
"src/site/xdoc/download_numbers.xml".
-This file is updated automatically by running the command:
-
- $ mvn commons:download-page
-
-
-(7)
-The "release notes" file will be created by gathering all the changes
-collected during development in the file "src/changes/changes.xml".
-Create it by running:
-
- $ mvn -Prelease-notes changes:announcement-generate
-
-Check the file for weird line breaks, and commit the updated files to git:
-
- $ git add src/site/site.xml \
- src/changes/changes.xml \
- pom.xml \
- src/site/xdoc/download_numbers.xml \
- RELEASE-NOTES.txt
-
-Check you did not forget any files:
-
- $ git status
-
-Commit the changes:
-
- $ git commit -m "Release candidate."
-
-
-(8)
-Create a GPG signed tag that will contain the whole source of this release
candidate.
-First, make sure once again that the workspace is up-to-date:
-
- $ git status
-
-Then, assuming the first candidate, the suffix will be "RC1" (this should
-be the same as in the "<properties>" in the "pom.xml"), and the command
-will be:
-
- $ git tag -u "__Your_key_id__" -s -m "RC1." NUMBERS_1_0_RC1
-
-If you have several GPG keys, you may prefer to use "-u keyId" to select a
specific
-key for signing the tag instead of "-s" which select automatically one key
-from the configured e-mail address.
-
-Check the tag GPG signature:
-
- $ git tag -v NUMBERS_1_0_RC1
-
-You will get something like:
-
- object cf4a9d70c9ac24dd7196995390171150e4e56451
- type commit
- tag NUMBERS_1_0_RC1
- tagger YourName <YourApacheEmail> 1418934614 +0100
-
- RC1.
-
-followed by GPG output lines.
-
-Remember the commit ID listed in the object line (here
cf4a9d70c9ac24dd7196995390171150e4e56451),
-as it is the most stable reference for traceability.
-
-Push everything (including the tag!) on the Apache repository:
-
- $ git push --tags
-
-
-(9)
-Switch to a new directory out of your regular workspace, and retrieve
-the official tag from the Apache repository:
-
- $ cd /tmp
- $ git clone https://git-wip-us.apache.org/repos/asf/commons-numbers.git
--branch NUMBERS_1_0_RC1
-
-In the command above, the --branch option accepts both branch names and tags
names,
-so we specify directly the tag here. Git will warn that the resulting workspace
-is in 'detached HEAD' state and 'git status' commands will warn that you are
not
-currently on any branch. This is expected in this situation.
-
-Check that the last commit has the id you noted in the previous step:
-
- $ cd commons-numbers
- $ git log -1
-
-
-(10)
-If this is your first release, you might need to add your GPG encryption
-key to the KEYS file. [If you have already done so, skip this section.]
-
-Retrieve the files from the SVN repository:
-
- $ svn co --depth=immediates \
-
https://__your_apache_logi...@svn.apache.org/repos/asf/commons/trunks-proper
-
-and follow the instructions at the top of the "KEYS" file.
-
-
-(11)
-Create and transfer the artifacts to the Nexus server (a.k.a. "deploy").
-
-Because the artifacts must be cryptographically signed, this step requires that
-a profile named "release" exists in the maven "settings.xml" configuration file
-which will contain the identifier of your GPG key (cf. sample "settings.xml"
-file). You will also have to follow the instructions at
-https://maven.apache.org/guides/mini/guide-encryption.html to set your password
-in the settings.xml file.
-
-You can then run
-
- $ mvn clean deploy -Prelease
-
-which will transfer the artifacts to the Nexus repository located at
- https://repository.apache.org/index.html#stagingRepositories
-
-This process transfers more files than really needed in the the "staging" (i.e.
-non official) maven repository. The files expected in the repository are
- commons-numbers-1.0.pom
- commons-numbers-1.0.jar
- commons-numbers-1.0.javadoc
- commons-numbers-1.0.sources
- commons-numbers-1.0.test-sources
- commons-numbers-1.0.tests
-and their associated fingerprints
- <file-name>.md5
- <file-name>.sha1
-and their signatures
- <file-name>.asc
-
-Nexus used to add "md5" and "sha1" checksums files to the "asc" files
-(cryptographic signature). If these fingerprints on signatures are
-present, they must be manually removed from Nexus staging area.
-
-The process also transfers the complete source and binaries distributions
files,
-(for each module):
- commons-numbers-<ModuleArtefactId>-1.0-bin.tar.gz
- commons-numbers-<ModuleArtefactId>-1.0-bin.zip
- commons-numbers-<ModuleArtefactId>-1.0-src.tar.gz
- commons-numbers-<ModuleArtefactId>-1.0-src.zip
-as well as their associated .md5 and .sha1 fingerprints and .asc signatures.
-All these files are not maven artifacts but rather distribution archives: They
-belong elsewhere; hence they must also been removed from the Nexus staging
-repository.
-
-As a measure of sanity check, the Nexus repository must be manually "closed"
-before other people review the deliverables just created.
-How to "close" the staging repository is explained at this page:
-
http://books.sonatype.com/nexus-book/reference/staging-repositories.html#staging-sect-closing
-
-
-(12)
-Create and upload the other distribution files to the Apache servers.
-
- (12a)
- Perform a server-side copy of the README.html from the "release" area of
- the Apache dist server to the "dev" area:
-
- $ svn cp
https://dist.apache.org/repos/dist/release/commons/numbers/README.html \
- https://dist.apache.org/repos/dist/dev/commons/numbers/README.html
-
- (12b)
- The modules "dist-archive" dedicated to creating the archive files.
- Run the following command:
-
- $ ( cd dist-archive && mvn assembly:single )
-
- (12c)
- Go to a temporary directory and check out the "dev" area.
-
- $ cd /tmp
- $ svn checkout https://dist.apache.org/repos/dist/dev/commons/numbers
- $ cd numbers
-
- (12d)
- Edit the "README.html" file to contain the released version number.
-
- (12e)
- Copy other files from the RC workspace:
-
- $ cp path-to-the-RC-workspace/RELEASE-NOTES.txt .
- $ cp path-to-the-RC-workspace/CONTRIBUTING.md .
- $ cp path-to-the-RC-workspace/README.md .
- $ cp path-to-the-RC-workspace/dist-archive/target/*-bin.* binaries
- $ cp path-to-the-RC-workspace/dist-archive/target/*-src.* source
-
- Currently, the commons-parent build does not create the
- * signatures (".asc"),
- * checksums (".md5"),
- * hashes (".sha1")
- of the distribution files. Hence, you have to create them "manually"!
- For the signature, the command would be
- $ gpg -ab file-to-sign
- For the hash and checksum, see e.g. the "Digest" Perl module.
-
- (12f)
- Commit to SVN:
-
- $ svn add \
- CONTRIBUTING.md \
- README.md \
- README.html \
- RELEASE-NOTES.txt \
- binaries/* \
- source/*
- $ svn commit -m "Distribution files for Commons Numbers v1.0 (RC1)."
-
-
-(13)
-As the web site staging area is shared among all commons components and
therefore
-could be published before the vote ends, it is not recommended to use the
standard
-staging area for the release candidate. So you will just archive the site and
-transfer it to your apache personal area for review.
-Here is how to do this using "lftp" to initiate the sftp transfer. "lftp"
supports
-a mirror command for recursive transfers; don't forget the -R flag for
uploading
-instead of downloading the site.
-If you haven't setup your login on home.apache.org you will need to go to
- https://id.apache.org/
-login and copy the contents of your
- ~/.ssh/id_rsa.pub
-file to "SSH Key (authorized_keys line)".
-Then run these commands:
-
- $ mvn clean site site:stage
- $ cd target
- $ mv staging commons-numbers-1.0-RC1-site
- $ lftp sftp://__your_apache_logi...@home.apache.org
- lftp y...@home.apache.org:~> cd public_html
- lftp y...@home.apache.org:~/public_html> mirror -R
commons-numbers-1.0-RC1-site
- lftp y...@home.apache.org:~/public_html> bye
-
-
-(14)
-Call to vote by sending a message to the "dev" ML with subject
-"[VOTE][RC1] Release Commons Numbers 1.0". You can use the following example as
-a starting point, replacing the URLs with the appropriate ones:
-----------
-This is a [VOTE] for releasing Apache Commons Numbers 1.0 (from RC6).
-
-
-Tag name:
- NUMBERS_1_0_RC6 (signature can be checked from git using 'git tag -v')
-
-Tag URL:
-
https://git-wip-us.apache.org/repos/asf?p=commons-numbers.git;a=commit;h=4581a4520315657a4219b37c81f5db80e4a4e43c
-
-Commit ID the tag points at:
- 4581a4520315657a4219b37c81f5db80e4a4e43c
-
-Site:
- http://home.apache.org/~erans/commons-numbers-1.0-RC6-site
-
-Distribution files (committed at revision 17284):
- https://dist.apache.org/repos/dist/dev/commons/numbers/
-
-Distribution files hashes (SHA1):
- c5e70a523160ed848194eeba0efa2b14d23c7a61 commons-numbers-1.0-bin.tar.gz
- 66d7701afc90aafa4c4b6e033b8df6cd84365161 commons-numbers-1.0-bin.zip
- ef56543c8882a0e4771de83ecf8b3be190f122cf commons-numbers-1.0-src.tar.gz
- 3dc56b0793d8bbd703a4efa68547eb58f6fb5b35 commons-numbers-1.0-src.zip
-
-KEYS file to check signatures:
- https://www.apache.org/dist/commons/KEYS
-
-Maven artifacts:
- https://repository.apache.org/content/repositories/orgapachecommons-1229/
-
-Please select one of the following options:
- [ ] +1 Release it.
- [ ] +0 Go ahead; I don't care.
- [ ] -0 There are a few minor glitches: ...
- [ ] -1 No, do not release it because ...
-
-This vote will be open for at least 72 hours, i.e. until 2016-12-10T00:00:00Z
-(this is UTC time).
-----------
-
-
-(15)
-If some blocking problems have been found in the release deliverables, cancel
-the vote by sending a "[CANCEL][VOTE]" message to the "dev" ML.
-After correcting the problems, you'll likely have to start again from step 3,
-4 or 5.
-
-
-(16)
-After at least 72 hours have elapsed, send a "[VOTE][RESULT]" mail to
-summarize the outcome of the vote. This should tally the votes cast,
-and state which are binding (PMC members). The vote needs at least three +1's
-from PMC members to pass.
-
-
-(17)
-The distribution files must be moved from the development area to the release
-area of the Apache dist server.
-
- (17a)
- Checkout the official distribution repository:
-
- $ svn co https://dist.apache.org/repos/dist/release/commons/numbers
-
- (17b)
- Copy the files from the checkout of the repository that was voted on:
-
- $ cd numbers
- $ rsync -Cavz path-to-RC-dev/numbers/ .
-
- (17c)
- Check (and possibly "svn add") files.
-
- (17d)
- Commit:
-
- $ svn commit -m "Release Commons Numbers v1.0 (from RC6)."
-
- (17e)
- Register the release at
- https://reporter.apache.org/addrelease.html?commons
-
-(18)
-Release (a.k.a. "promote") the artifacts on the Nexus server, as shown here:
-
http://books.sonatype.com/nexus-book/reference/staging-repositories.html#staging-sect-releasing
-
-
-(19)
-Publish the web site. This is done by first committing the web site to the
-staging area, and then by publishing the staging area (which is shared among
-all commons components).
-
-In order to commit the web site to the staging area, look at the subversion
-workspace that was automatically checked out during the 'mvn site' command in
-folder site-content. Note that svn commits in the site-content directory are
-immediately synced with the live site and so your changes should show up in a
-few minutes once you commit the new site. You can also check out the site
-directly by yourself elsewhere:
-
- $ svn checkout
https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-numbers
site-content
-
-Remove all files there (except .svn folder) and move all the files from the
site.
-
- $ cd site-content
- $ rm -rf *
- $ cp -pR ../target/commons-numbers-1.0-RC1-site/* .
-
-Check for new or deleted files:
- $ svn status
-and "svn add" or "svn del" them if necessary.
-
-Commit the new contents of the web site:
- $ svn commit -m "Commons Numbers v1.0 was released (from RC6). Web site
update"
-
-
-(20)
-The Javadoc for several versions is kept available on the website, under the
-"javadocs" directory.
-There is a huge number of files that never change, so they are not retrieved by
-default in the working copy when running 'svn checkout'.
-The Javadoc must therefore be copied manually using server side copy from the
-"apidocs" directory after release, in order for the links to former versions
-to work. This is done as follows:
-
- $ export NUMBERS_WEB_SITE_SVN_REVISION=1002658
- $ export NUMBERS_RELEASE_VERSION=1.0
- $ svnmucc -U
https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-numbers
\
- cp $NUMBERS_WEB_SITE_SVN_REVISION commons-numbers-client-api/apidocs \
-
commons-numbers-client-api/javadocs/api-$NUMBERS_RELEASE_VERSION \
- cp $NUMBERS_WEB_SITE_SVN_REVISION commons-numbers-core/apidocs \
-
commons-numbers-core/javadocs/api-$NUMBERS_RELEASE_VERSION \
- cp $NUMBERS_WEB_SITE_SVN_REVISION commons-numbers-simple/apidocs \
-
commons-numbers-simple/javadocs/api-$NUMBERS_RELEASE_VERSION \
- cp $NUMBERS_WEB_SITE_SVN_REVISION commons-numbers-sampling/apidocs \
-
commons-numbers-sampling/javadocs/api-$NUMBERS_RELEASE_VERSION \
- cp $NUMBERS_WEB_SITE_SVN_REVISION commons-numbers-jmh/apidocs \
-
commons-numbers-jmh/javadocs/api-$NUMBERS_RELEASE_VERSION \
- cp $NUMBERS_WEB_SITE_SVN_REVISION commons-numbers-examples/apidocs \
-
commons-numbers-examples/javadocs/api-$NUMBERS_RELEASE_VERSION \
- -m "Commons NUMBERS: Copying $NUMBERS_RELEASE_VERSION apidocs to
versioned directories for the long-term links."
-
-Now wait a few minutes for the live site to fully sync and then check
- http://commons.apache.org/proper/commons-numbers/
-to make sure that everything looks correct.
-
-
-(21)
-Put the official final tag to point at the same commit as the last release
candidate tag:
-
- $ git tag -u "__Your_key_id__" -s -m "RC6 becomes v1.0 official release."
NUMBERS_1_0 cf4a9d70c9ac24dd7196995390171150e4e56451
- $ git push --tags
-
-
-(22)
-Switch back to the "master" branch.
-We now prepare for the next round of development (here we assume that the
-next version will be 1.1).
-
- (22a)
- Edit "doap_numbers.rdf" to add the just released version date.
- It is located at
- https://svn.apache.org/repos/asf/commons/cms-site/trunk/doap
- in the SVN repository.
-
- (22b)
- Retrieve files from the "1.0-release branch" (so that the web site will
- contain up-to-date information):
-
- $ git checkout 1.0-release src/site/xdoc/download_numbers.xml
- $ git checkout 1.0-release src/changes/changes.xml
-
- Edit "src/changes/changes.xml" to add a new section for the next release,
- setting the release date and description to "TBD".
- Then commit them.
-
- (22c)
- Edit every "pom.xml" file (i.e. for each module) to contain
-
- <version>1.1-SNAPSHOT</version>
-
- Double-check that the "pom.xml" files *really* have a "-SNAPSHOT" suffix
- in the "<version>" property.
- Then commit them.
-
- Push everything to the Apache repository.
-
-
-(23)
-Allow for the web site mirrors to be updated (possibly several hours); then
-send (from your apache account) a release announcement to the following ML:
- annou...@apache.org
- d...@commons.apache.org
- u...@commons.apache.org
-
-If you don't have it setup already you can follow these instructions to send
-email from your apache account :
-
-https://reference.apache.org/committer/email#sendingemailfromyourapacheorgemailaddress
-
-You can use the following message as a template:
-
-----------
-The Apache Commons Team is pleased to announce the availability of
-version 1.0 of "Apache Commons Numbers".
-
-Apache Commons Numbers provides number types such as complex, quaternion
-fraction, and associated utilities.
-
-The release notes can be reviewed at
- https://www.apache.org/dist/commons/numbers/RELEASE-NOTES.txt
-
-Distribution packages can be downloaded from
- https://commons.apache.org/proper/commons-numbers/download_numbers.cgi
-
-When downloading, please verify signatures using the KEYS file
-available at
- https://www.apache.org/dist/commons/KEYS
-
-Maven artifacts are also available in the central Maven repository:
- https://repo1.maven.org/maven2/org/apache/commons/
-
-
-The Apache Commons Team
-----------
+The Commons RNG project contains up-to-date information for a step-by-step
+recipe to create release candidate. Please refer to it:
+
https://gitbox.apache.org/repos/asf?p=commons-rng.git;a=blob;f=doc/release/release.howto.txt
