You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2021/08/21 05:38:01 UTC
[commons-geometry] 10/13: adding release and development
documentation
This is an automated email from the ASF dual-hosted git repository.
mattjuntunen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-geometry.git
commit 5944830ffb7645a58f6764fcd5c88af9045ff70d
Author: Matt Juntunen <ma...@apache.org>
AuthorDate: Sat Aug 21 00:30:24 2021 -0400
adding release and development documentation
---
doc/development/development.howto.txt | 30 ++
doc/release/copyLongTermJavadoc.sh | 56 +++
doc/release/release-howto.txt | 880 ++++++++++++++++++++++++++++++++++
doc/release/settings-security.xml | 22 +
doc/release/settings.xml | 63 +++
5 files changed, 1051 insertions(+)
diff --git a/doc/development/development.howto.txt b/doc/development/development.howto.txt
new file mode 100644
index 0000000..7776ee7
--- /dev/null
+++ b/doc/development/development.howto.txt
@@ -0,0 +1,30 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+This document summarizes the development process of Commons Geometry:
+
+1. The "master" branch collects all modifications that will be part
+ of the next release.
+ Usually, non trivial changes should not be committed directly to the "master"
+ branch; they should be merged from a branch specifically created for
+ that purpose (see next point).
+2. Work on an identified issue (bug fix or new feature) must be done in a
+ new branch named after its corresponding report in the bug-tracking
+ system (JIRA), e.g. "feature-GEOMETRY-123".
+ After completion, and in the absence of technical objections, the feature
+ branch is merged into the "master" branch, using the "--no-ff" git
+ option.
+ That feature branch is then deleted.
diff --git a/doc/release/copyLongTermJavadoc.sh b/doc/release/copyLongTermJavadoc.sh
new file mode 100755
index 0000000..0b46c2a
--- /dev/null
+++ b/doc/release/copyLongTermJavadoc.sh
@@ -0,0 +1,56 @@
+#!/bin/bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -e
+
+# List of all modules paths for which the long-term Javadoc links must be copied
+# We keep only the official distribution (i.e. _not_ "commons-geometry-examples").
+MODULES=(commons-geometry-core \
+ commons-geometry-euclidean \
+ commons-geometry-spherical \
+ commons-geometry-io-core \
+ commons-geometry-io-euclidean)
+
+while getopts r:v: option
+do
+ case "${option}"
+ in
+ r) REVISION=${OPTARG};;
+ v) VERSION=${OPTARG};;
+ esac
+done
+
+if [ "$REVISION" == "" ]; then
+ echo "Missing SVN revision: Specify '-r <svn commit id>'";
+ exit 1;
+fi
+
+if [ "$VERSION" == "" ]; then
+ echo "Missing component version: Specify '-v <component version id>'";
+ exit 1;
+fi
+
+for mod in ${MODULES[@]}; do
+ echo $mod
+ CPLIST+=" cp $REVISION $mod/apidocs $mod/javadocs/api-$VERSION"
+done
+
+echo -n "Copying long-term links ... "
+svnmucc -U https://svn.apache.org/repos/infra/websites/production/commons/content/proper/commons-geometry \
+ $CPLIST \
+ -m "Commons Geometry: Copying $VERSION apidocs to versioned directories for the long-term links."
+echo "Done."
diff --git a/doc/release/release-howto.txt b/doc/release/release-howto.txt
new file mode 100644
index 0000000..63d604c
--- /dev/null
+++ b/doc/release/release-howto.txt
@@ -0,0 +1,880 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# 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 Geometry component. Note that more general instructions valid
+for all components, including [geometry], are available on the Apache Commons
+main site: at "https://commons.apache.org/releases/prepare.html" and
+"https://commons.apache.org/releases/release.html".
+
+When performing a release it is recommended to make notes of any changes that
+were required to those detailed in this document. The changes can be incorporated
+after a successful release.
+
+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.
+ Ensure the binary compatibility release version is correctly set in the pom.xml using the
+ appropriate properties:
+ <properties>
+ <!-- ... -->
+ <commons.release.version>1.0</commons.release.version>
+ <commons.bc.version>1.0</commons.bc.version>
+ <!-- ... -->
+ </properties>
+ Check all the issues reported by the "Clirr" and "japicmp" plugin.
+ * Clear all "CheckStyle" warnings.
+ * Make sure that the construct reported by "SpotBugs" and "PMD" are intentional.
+ * Mark all issues fixed in the release as resolved in the bug-tracking system (JIRA). Issues marked
+ as 'Implemented' or 'Fixed' will appear in the changes report. Add a corresponding entry in
+ "src/changes/changes.xml" for the JIRA ticket.
+
+
+(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
+
+ $ JAVA_HOME="__Path_to_a_JDK__" mvn -Duser.name="__Your_Apache_id__" -Dcommons.release.dryRun=true -Ptest-deploy -Prelease -Pcommons-geometry-examples clean test package site deploy
+
+ should create the artifacts in the "target/deploy" directory. (Note that this
+ command uses the commons-geometry-examples profile to include the example modules
+ in the build. These artifacts are not part of the binary distribution and will not
+ be present in the deploy directory. However, it is important to include them at this
+ stage in order to ensure that they build correctly.)
+
+ 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).
+ Note: If running from a remote terminal, you might need to tune the "gpg-agent"
+ configuration file
+ ~/.gnupg/gpg-agent.conf
+ to contain the following statements:
+ ---CUT---
+ enable-ssh-support
+ pinentry-program /usr/bin/pinentry-tty
+ ---CUT---
+ and execute
+ $ export GPG_TTY=$(tty)
+ in order to set up the environment for entering the passphrase.
+
+ (1b)
+ When the above works, you can test the creation of the full distribution
+ files with the following commands:
+
+ $ cd dist-archive
+ $ mvn clean install -Prelease -Dcommons.release.dryRun=true
+
+ The "dist-archive/target" directory will then contain those files:
+ commons-geometry-1.0-SNAPSHOT-bin.tar.gz
+ commons-geometry-1.0-SNAPSHOT-bin.zip
+ commons-geometry-1.0-SNAPSHOT-src.tar.gz
+ commons-geometry-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
+
+(Optional)
+Modify the dist-archive/pom.xml to update the release manager name and GPG signing key
+to be used for the 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 "1.x-dev"
+
+ $ git merge 1.x-dev
+
+ (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
+release branch and *not* on the master branch.
+
+In particular:
+ * Update and commit the "src/site/site.xml" file in each maven module 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>
+
+ This can be done using maven:
+
+ $ mvn versions:set -DnewVersion=1.0 -DgenerateBackupPoms=false -Pcommons-geometry-examples
+
+ You will need to update the version in dist-archive/pom.xml manually.
+
+ 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_geometry.xml".
+This file is updated automatically by running the command:
+
+ $ mvn -N commons-build: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
+
+Ensure the formatting of the RELEASE-NOTES.txt is consistent. Compare the main
+header description to the previous release notes in src/site/resources/release-notes/
+and update the line wrap formatting to match. Remove trailing whitespace.
+Ensure the lines wrap at 100 characters.
+Note that wrapping is taken from changes.xml which should be written to wrap
+at 100 characters but allowing for a indent on the first line due to the
+issue field. Update changes.xml if appropriate.
+
+Append the previous release notes from src/site/resources/release-notes/ to the current one:
+
+ $ (echo "=============================================================================" &&
+ cat src/site/resources/release-notes/RELEASE-NOTES-<old version>.txt) >> RELEASE-NOTES.txt
+
+Copy the RELEASE-NOTES.txt to src/site/resources/release-notes:
+
+ $ cp RELEASE-NOTES.txt src/site/resources/release-notes/RELEASE-NOTES-<version>.txt
+
+Update the src/site/xdoc/release-history.xml to include the latest version. This generates
+the release history page on the web site.
+
+Commit the updated files to git:
+
+ $ git add .
+
+Check the modified 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" commons-geometry-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 commons-geometry-1.0-rc1
+
+You will get something like:
+
+ object cf4a9d70c9ac24dd7196995390171150e4e56451
+ type commit
+ tag commons-geometry-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://gitbox.apache.org/repos/asf/commons-geometry.git --branch commons-geometry-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-geometry
+ $ 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=files \
+ https://dist.apache.org/repos/dist/release/commons/svn
+
+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
+for your apache id in the settings.xml file which is used for Nexus repository staging.
+
+The release process requires commit access for the commons SVN repository used to host the
+web site. This will use the provided 'user.name' for SVN. If your SVN is not set-up to
+cache passwords then a password must be provided. This can be done using a <server> section in
+the maven settings.xml file. Typically the username is the same for Nexus repository staging
+(i.e. your apache id) so the server 'apache.releases.https' configured in the example
+settings.xml file can be used by setting the commons.distServer property for the commons release
+plugin (see https://commons.apache.org/proper/commons-release-plugin/index.html).
+
+You can then run
+
+ With site generation:
+
+ $ mvn -Duser.name="__Your_Apache_id__" [-Dcommons.distServer=apache.releases.https] -Prelease -Pcommons-geometry-examples clean package site site:stage deploy
+
+ Or without the site generation:
+
+ $ mvn -Duser.name="__Your_Apache_id__" [-Dcommons.distServer=apache.releases.https] -Prelease -Pcommons-geometry-examples clean deploy
+
+ The site can be generated afterwards using 'mvn package site site stage'.
+
+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-geometry-<ModuleArtifactID>-1.0.pom
+ commons-geometry-<ModuleArtifactID>-1.0.jar
+ commons-geometry-<ModuleArtifactID>-1.0.javadoc
+ commons-geometry-<ModuleArtifactID>-1.0.sources
+ commons-geometry-<ModuleArtifactID>-1.0.test-sources
+ commons-geometry-<ModuleArtifactID>-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 used to transfer the complete source and binaries distributions files,
+(for each module):
+ commons-geometry-<ModuleArtifactId>-1.0-bin.tar.gz
+ commons-geometry-<ModuleArtifactId>-1.0-bin.zip
+ commons-geometry-<ModuleArtifactId>-1.0-src.tar.gz
+ commons-geometry-<ModuleArtifactId>-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://www.apache.org/dev/publishing-maven-artifacts.html#close-stage
+
+
+(12)
+Create and upload the other distribution files to the "dev" distribution
+area on the Apache servers.
+
+ (12a)
+ The module "dist-archive" is dedicated to creating the archive files.
+ Run the following commands:
+
+ $ cd dist-archive
+ $ mvn clean install -Prelease -Dcommons.release.dryRun=true
+
+ (12b)
+ Go to a temporary directory and check out the "dev" area.
+
+ $ cd /tmp
+ $ svn checkout https://dist.apache.org/repos/dist/dev/commons/geometry
+ $ cd geometry
+
+ (12c)
+ Create a new folder for the release candidate artifacts.
+
+ $ svn mkdir 1.0-RC1
+
+ (12d)
+ Copy the README.html and HEADER.html files from the last released version and add to the new directory.
+
+ $ curl https://dist.apache.org/repos/dist/release/commons/geometry/README.html > 1.0-RC1/README.html
+ $ curl https://dist.apache.org/repos/dist/release/commons/geometry/HEADER.html > 1.0-RC1/HEADER.html
+
+ (12e)
+ Edit the "README.html" file to contain the released version number.
+
+ (12f)
+ 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/dist-archive/target/*-bin.* binaries
+ $ cp path-to-the-RC-workspace/dist-archive/target/*-src.* source
+
+ (12g)
+ Create copies of the HEADER.html and README.html files in the subdirectories
+ $ cp *.html binaries/
+ $ cp *.html source/
+
+ Currently, the commons-parent build does not create the
+ * signatures (".asc"),
+ * hashes (".sha512")
+ of the distribution files. Hence, you have to create them "manually"!
+ For the signature, the command is
+ $ gpg -ab file-to-sign
+ For the hash, the commands is
+ $ sha512sum -b input-file > input-file.sha512
+
+ Double-check the signatures and hashes with the following:
+ $ gpg --verify asc-file
+ $ sha512sum -c hash-file
+
+ (12h)
+ Commit to SVN:
+
+ $ svn add \
+ CONTRIBUTING.md \
+ README.html \
+ RELEASE-NOTES.txt \
+ binaries/* \
+ source/*
+ $ svn commit -m "Distribution files for Commons Geometry 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:
+
+ (Optional. Use this if the release step in (11) was performed without site generation.
+ Do not run 'clean' as it will delete the release source/binary artifacts and the release
+ plugin cannot be used to generate the template VOTE.txt file with the correct hashes.)
+ $ mvn -Pcommons-geometry-examples package site site:stage
+
+ $ cd target
+ $ mv staging commons-geometry-1.0-RC1-site
+ $ lftp sftp://__Your_apache_login__@home.apache.org
+ lftp you@home.apache.org:~> mkdir public_html
+ lftp you@home.apache.org:~> cd public_html
+ lftp you@home.apache.org:~/public_html> mirror -R commons-geometry-1.0-RC1-site
+ lftp you@home.apache.org:~/public_html> bye
+
+
+(14)
+[NOTE: The "Commons release-plugin" can generate the text for the "[VOTE]"
+message. However, the script makes some (incorrect) assumptions and produces
+a result that must be heavily edited.]
+
+Template the vote using this command (run from the dist-archive module):
+
+ $ mvn org.apache.commons:commons-release-plugin:vote-txt -Dcommons.nexus.repo.id=1566
+
+See target/VOTE.txt. This must be heavily edited. It is useful to generate the release hashes.
+
+Call to vote by sending a message to the "dev" ML with subject
+"[VOTE] Release Commons Geometry 1.0 based on RC1". You can use the following example as
+a reference point, replacing the URLs with the appropriate ones:
+----------
+We have fixed quite a few bugs and added some significant enhancements since Apache Commons Geometry 1.0-beta1 was released,
+so I would like to release Apache Commons Geometry 1.0.
+
+Apache Commons Geometry (full distribution) 1.0 RC4 is available for review here:
+ https://dist.apache.org/repos/dist/dev/commons/geometry/1.0-RC4 (svn revision 49526)
+
+The Git tag commons-geometry-1.0-rc4 commit for this RC is 5326851864f93a486409562628afaaa485b6d99f which you can browse here:
+ https://gitbox.apache.org/repos/asf?p=commons-geometry.git;a=commit;h=5326851864f93a486409562628afaaa485b6d99f
+You may checkout this tag using:
+ git clone https://gitbox.apache.org/repos/asf/commons-geometry.git --branch commons-geometry-1.0-rc4 commons-geometry-1.0-rc4
+
+Maven artifacts are here:
+ https://repository.apache.org/content/repositories/orgapachecommons-1566/
+
+These are the artifacts and their hashes:
+
+#Release SHA-512s
+#Mon Aug 16 21:52:18 EDT 2021
+commons-geometry-1.0-bin.tar.gz=b170b25f0c4c7837a51c8c3b37aa970c755c5610b16e6afa82f4cfea6dfa14f347366932e4e0ded921150ad4ad349f1d16661934925da6ece7253599fbd90cf0
+commons-geometry-1.0-bin.zip=3a1c4de02f684d9837ee3284b3a35bac2369d3ea9994354218bcc0d3480330c174054b536dc02104b55a3dadee91c56a66742dd830f19dbdee5f765faf1ec596
+commons-geometry-1.0-src.tar.gz=ad2c89958a3a6278135b2c820bc5c6d97edc49ea8dd119c44c49e764248e068ff0404b04cb620d0f10a7172b69ee0907f39483119c1fcd695ffe58f4c0d3731a
+commons-geometry-1.0-src.zip=45c467545a84347b89319077c5c1221a5e908894a32f61f713909b2905d006de89cf4a73dc99b29b31c01c2fa28a73f71bd4ff4d530f2264a06c6a118a02b8ad
+
+(no need for .asc hashes!)
+
+I have tested this with ***'mvn clean install site'*** using:
+***
+Apache Maven 3.5.3 (3383c37e1f9e9b3bc3df5050c29c8aff9f295297; 2018-02-24T14:49:05-05:00)
+Maven home: /home/matt/tools/maven/apache-maven-3.5.3
+Java version: 1.8.0_292, vendor: Private Build
+Java home: /usr/lib/jvm/java-8-openjdk-amd64/jre
+Default locale: en_US, platform encoding: UTF-8
+OS name: "linux", version: "5.4.0-80-generic", arch: "amd64", family: "unix"
+
+Apache Maven 3.5.3 (3383c37e1f9e9b3bc3df5050c29c8aff9f295297; 2018-02-24T14:49:05-05:00)
+Maven home: /home/matt/tools/maven/apache-maven-3.5.3
+Java version: 11.0.2, vendor: Oracle Corporation
+Java home: /home/matt/lang/java/jdk-11.0.2
+Default locale: en_US, platform encoding: UTF-8
+OS name: "linux", version: "5.4.0-80-generic", arch: "amd64", family: "unix"
+
+Apache Maven 3.5.3 (3383c37e1f9e9b3bc3df5050c29c8aff9f295297; 2018-02-24T14:49:05-05:00)
+Maven home: /home/matt/tools/maven/apache-maven-3.5.3
+Java version: 16.0.1, vendor: AdoptOpenJDK
+Java home: /home/matt/lang/java/jdk-16.0.1+9
+Default locale: en_US, platform encoding: UTF-8
+OS name: "linux", version: "5.4.0-80-generic", arch: "amd64", family: "unix"
+
+***
+
+Details of changes since 1.0-beta1 are in the release notes:
+ https://dist.apache.org/repos/dist/dev/commons/geometry/1.0-RC4/RELEASE-NOTES.txt
+
+Site:
+ https://home.apache.org/~mattjuntunen/commons-geometry-1.0-RC4-site/
+ (note some *relative* links are broken and the 1.0 directories are not yet created - these will be OK once the site is deployed.)
+
+CLIRR Report (compared to ${commons.bc.version}):
+ N/A
+
+JApiCmp Report (compared to ${commons.bc.version}):
+ N/A
+
+RAT Report:
+ https://home.apache.org/~mattjuntunen/commons-geometry-1.0-RC4-site/rat-report.html
+
+KEYS:
+ https://www.apache.org/dist/commons/KEYS
+
+Please review the release candidate and vote.
+This vote will close no sooner that 72 hours from now.
+
+ [ ] +1 Release these artifacts
+ [ ] +0 OK, but...
+ [ ] -0 OK, but really should fix...
+ [ ] -1 I oppose this release because...
+
+Thank you,
+
+Matt Juntunen,
+Release Manager (using key 7DD53AEFEDF1C3D392B51EBE346F4FCECFB70B1A)
+----------
+
+
+(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/geometry
+
+ Identify symbolic links:
+
+ $ find . -type l
+
+ (17b)
+ Copy the files from the checkout of the repository that was voted on:
+
+ $ cd geometry
+ $ rsync -Cavz path-to-RC-dev/geometry/ .
+
+ [Note: This might overwrite symbolic links; in this case, do a "svn
+ revert" in order to restore the files that should not be updated.]
+
+ (17c)
+ Check files. The following is useful:
+
+ $ svn diff --summarize
+
+ Perform a "svn add" for the new release artefacts.
+ Perform a "svn del" for the old release(s) artefacts.
+
+ (17d)
+ Commit:
+
+ $ svn commit -m "Release Commons Geometry v1.0 (from RC1)."
+
+ (17e)
+ Register the release at
+ https://reporter.apache.org/addrelease.html?commons
+
+
+(18)
+Login to the Nexus repository located at
+ https://repository.apache.org/index.html#stagingRepositories
+
+Release (a.k.a. "promote") the artifacts on the Nexus server, as shown here:
+ http://www.apache.org/dev/publishing-maven-artifacts.html#promote
+
+
+(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-geometry 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-geometry-1.0-RC1-site/* .
+
+Check for new or deleted files:
+ $ svn status
+and "svn add" or "svn del" them if necessary.
+
+It is very useful to know changes to the project since the last release. The clirr and japicmp
+reports are helpful for the public API. Changes in commons-geometry-examples are not subject to these
+reports and require developer insight. If in doubt do not delete files.
+
+The following commands are useful:
+
+Reverting:
+
+ $ svn status | grep ^M
+ $ svn status | awk '{if ($1 == "M") print $2 }' | xargs svn revert
+
+Revert deleted archived javadocs:
+ $ svn status | grep /javadocs | awk '{if ($1 == "!") print $2 }' | xargs svn revert
+
+Deleting (**do not** delete old javadocs):
+
+ $ svn status | grep -v javadocs | grep ^!
+ $ svn status | grep -v javadocs | awk '{if ($1 == "!") print $2 }' | xargs svn del
+
+Adding:
+
+ $ svn status | grep ^?
+ $ svn status | awk '{if ($1 == "?") print $2 }' | xargs svn add
+
+Commit the new contents of the web site:
+ $ svn commit -m "Commons Geometry v1.0 was released (from RC1). Web site update"
+
+Note the SVN website revision for the next step.
+
+
+Edit the file component_releases.properties to hold the current version and release date for
+your component:
+
+ $ svn checkout --depth files https://svn.apache.org/repos/asf/commons/cms-site/trunk/conf/
+
+ [edit file]
+
+ $ (cd conf && svn commit -m "Commons Geometry v1.0 was released (from RC1)")
+
+
+(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 using the "doc/release/copyLongTermJavadoc.sh" script
+(options are the svn revision and the component's new version).
+
+Wait a few minutes for the live site to fully sync and then check
+ https://commons.apache.org/proper/commons-geometry/
+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 "RC1 becomes v1.0 official release." rel/commons-geometry-1.0 __commit_hash__
+ $ 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_geometry.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 changes made on the "1.0-release branch" (so that the web site will
+ contain up-to-date information):
+
+ $ git cherry-pick -n [release commit range]
+
+ 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>
+
+ This can be done using maven:
+
+ $ mvn release:update-versions -DautoVersionSubmodules=true -Prelease
+
+ You will only be prompted for the desired version number once.
+ This will miss the dist-archive/pom.xml for all the dependencies.
+ These should be updated manually.
+ Double-check that the "pom.xml" files *really* have a "-SNAPSHOT" suffix
+ in the "<version>" property.
+ Then commit them.
+
+ (22d)
+ Update the README.md files to refer the latest release. These files are
+ auto-generated from the commons maven plugin using 'mvn common:readme-md'.
+ The generated README.md files may have been edited for the multi-module
+ set-up with extra text added to the main README.md.
+
+ An update will involve:
+
+ 1. Replacing the <version>1.0-beta1</version> example XML for the maven dependency to
+ <version>1.0</version>.
+ 2. Updating any badges for Javadocs. This can be done using search and replace
+ of '1.0-beta1.svg' for '1.0-beta1.svg' and '/1.0-beta1)' for '/1.0)'.
+
+ Check the changes using 'git diff' and commit.
+
+ (22e)
+ Update the <commons.release.version> tag in the master pom for the latest release.
+
+
+(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:
+ announce@apache.org
+ dev@commons.apache.org
+ user@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:
+
+Subject:
+[ANNOUNCEMENT] Apache Commons Geometry Version 1.0 Released
+----------
+The Apache Commons Team is pleased to announce the availability of
+version 1.0 of "Apache Commons Geometry".
+
+The Apache Commons Geometry project provides geometric types and utilities.
+
+Changes in this version include:
+
+***<Include release notes inline wrapped to 80 characters>***
+
+Historical list of changes:
+ https://commons.apache.org/proper/commons-geometry/changes-report.html
+
+For complete information on Apache Commons Geometry, including instructions on how
+to submit bug reports, patches, or suggestions for improvement, see the
+Apache Commons Geometry website:
+ https://commons.apache.org/proper/commons-geometry/
+
+Distribution packages can be downloaded from
+ http://commons.apache.org/proper/commons-geometry/download_geometry.cgi
+
+
+Matt Juntunen,
+Apache Commons Team
+----------
+
+
+(24)
+Update JIRA to close all issues resolved in this release and prepare for the next version.
+
+ (24a)
+ Log in to JIRA:
+ https://issues.apache.org/jira/projects/GEOMETRY
+
+ (24b)
+ Batch close resolved issues without sending notification e-mails:
+
+ - Click 'View all issues and filters'.
+ - Enter in the search field: project = GEOMETRY AND status = resolved
+ - Select "Tools" in the top right and choose "Bulk Change" for all of your relevant issues.
+ Step 1: Select the issues to close.
+ Step 2: Select 'Transition issues'.
+ Step 3: Select to close.
+ Step 4: Enter comment: 'Closed by release 1.0'.
+ Unselect 'Send mail for this update'.
+ Confirm.
+
+ (24c)
+ Manage the JIRA version for the release.
+
+ Click 'Project settings > Versions'.
+
+ Add a new version:
+ - Enter the new version number in the field and click 'Add'.
+
+ Set the release date for the recently release version:
+ - Click the released version.
+ - Click 'Release' and enter the date.
+
+
+(25)
+Finally revise the release notes (this document) with any changes to improve the release process.
diff --git a/doc/release/settings-security.xml b/doc/release/settings-security.xml
new file mode 100644
index 0000000..8111ca4
--- /dev/null
+++ b/doc/release/settings-security.xml
@@ -0,0 +1,22 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+<settingsSecurity>
+ <master>
+ {YBj6__Your_encrypted_master_password__3iR4=}
+ </master>
+</settingsSecurity>
diff --git a/doc/release/settings.xml b/doc/release/settings.xml
new file mode 100644
index 0000000..3123dc0
--- /dev/null
+++ b/doc/release/settings.xml
@@ -0,0 +1,63 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+<settings>
+
+ <servers>
+ <!-- To publish a snapshot -->
+ <server>
+ <id>apache.snapshots.https</id>
+ <username>__Your_apache_login__</username>
+ <password>{0Lbb__Your_encrypted_password__O4sQ=}</password>
+ </server>
+
+ <!-- To publish a release -->
+ <server>
+ <id>apache.releases.https</id>
+ <username>__Your_apache_login__</username>
+ <password>{0Lbb__Your_encrypted_password__O4sQ=}</password>
+ </server>
+
+ <!-- To stage the web site -->
+ <server>
+ <id>stagingSite</id>
+ <username>__Your_apache_login__</username>
+ <!-- This will use the default ssh key pair, whose public part must be
+ copied to the ~/.ssh/authorized_keys file on the server. -->
+ </server>
+
+ <!-- To publish the web site -->
+ <server>
+ <id>people.apache.org</id>
+ <username>__Your_apache_login__</username>
+ <!-- This will use the default ssh key pair, whose public part must be
+ copied to the ~/.ssh/authorized_keys file on the server. -->
+ </server>
+
+ </servers>
+
+ <profiles>
+ <profile>
+ <id>release</id>
+ <properties>
+ <gpg.keyname>__Your_key_identifier__</gpg.keyname>
+ <gpg.executable>gpg2</gpg.executable>
+ </properties>
+ </profile>
+ </profiles>
+
+</settings>