Merge pull request #1148 from Fenn-CS/3816.improve-release-checklist

Improve Release Checklist

.github/CONTRIBUTING.rst

@@ -18,3 +18,9 @@ Examples of contributions include:
 
 Before authoring or reviewing a patch,
 please familiarize yourself with the `Coding Standards <https://tahoe-lafs.org/trac/tahoe-lafs/wiki/CodingStandards>`_ and the `Contributor Code of Conduct <../docs/CODE_OF_CONDUCT.md>`_.
+
+
+🥳 First Contribution?
+======================
+
+If you are committing to Tahoe for the very first time, consider adding your name to our contributor list in `CREDITS <../CREDITS>`__

README.rst

@@ -97,6 +97,13 @@ As a community-driven open source project, Tahoe-LAFS welcomes contributions of
 
 Before authoring or reviewing a patch, please familiarize yourself with the `Coding Standard <https://tahoe-lafs.org/trac/tahoe-lafs/wiki/CodingStandards>`__ and the `Contributor Code of Conduct <docs/CODE_OF_CONDUCT.md>`__. 
 
+
+🥳 First Contribution?
+----------------------
+
+If you are committing to Tahoe for the very first time, it's required that you add your name to our contributor list in `CREDITS <CREDITS>`__. Please ensure that this addition has it's own commit within your first contribution.
+
+
 🤝 Supporters
 --------------
 

docs/gpg-setup.rst

@@ -0,0 +1,18 @@
+Preparing to Authenticate Release (Setting up GPG)
+--------------------------------------------------
+
+In other to keep releases authentic it's required that releases are signed before being
+published. This ensure's that users of Tahoe are able to verify that the version of Tahoe
+they are using is coming from a trusted or at the very least known source.
+
+The authentication is done using the ``GPG`` implementation of ``OpenGPG`` to be able to complete 
+the release steps you would have to download the ``GPG`` software and setup a key(identity).
+
+- `Download <https://www.gnupg.org/download/>`__ and install GPG for your operating system.
+- Generate a key pair using ``gpg --gen-key``. *Some questions would be asked to personalize your key configuration.*
+
+You might take additional steps including:
+
+- Setting up a revocation certificate (Incase you lose your secret key)
+- Backing up your key pair
+- Upload your fingerprint to a keyserver such as `openpgp.org <https://keys.openpgp.org/>`__

docs/index.rst

@@ -29,6 +29,7 @@ Contents:
    contributing
    CODE_OF_CONDUCT
    release-checklist
+   gpg-setup
 
    servers
    helper

docs/release-checklist.rst

@@ -3,9 +3,8 @@
 Release Checklist
 =================
 
-These instructions were produced while making the 1.15.0 release. They
-are based on the original instructions (in old revisions in the file
-`docs/how_to_make_a_tahoe-lafs_release.org`).
+This release checklist specifies a series of checks that anyone engaged in 
+releasing a version of Tahoe should follow.
 
 Any contributor can do the first part of the release preparation. Only
 certain contributors can perform other parts. These are the two main
@@ -13,9 +12,12 @@ sections of this checklist (and could be done by different people).
 
 A final section describes how to announce the release.
 
+This checklist is based on the original instructions (in old revisions in the file
+`docs/how_to_make_a_tahoe-lafs_release.org`).
+
 
 Any Contributor
----------------
+===============
 
 Anyone who can create normal PRs should be able to complete this
 portion of the release process.
@@ -32,13 +34,35 @@ Tuesday if you want to get anything in").
 
 - Create a ticket for the release in Trac
 - Ticket number needed in next section
+- Making first release? See `GPG Setup Instructions <gpg-setup.rst>`__ to make sure you can sign releases. [One time setup]
+
+Get a clean checkout
+````````````````````
+
+The release proccess involves compressing source files and putting them in formats 
+suitable for distribution such as ``.tar.gz`` and ``zip``. That said, it's neccesary to 
+the release process begins with a clean checkout to avoid making a release with
+previously generated files.
+
+- Inside the tahoe root dir run ``git clone . ../tahoe-release-x.x.x`` where (x.x.x is the release number such as 1.16.0). 
+
+.. note:: 
+     The above command would create a new directory at the same level as your original clone named ``tahoe-release-x.x.x``. You can name this folder however you want but it would be a good 
+     practice to give it the release name. You MAY also discard this directory once the release
+     process is complete.
+
+Get into the release directory and install dependencies by running 
+
+- cd ../tahoe-release-x.x.x (assuming you are still in your original clone)
+- python -m venv venv
+- ./venv/bin/pip install --editable .[test]
 
 
 Create Branch and Apply Updates
 ```````````````````````````````
 
-- Create a branch for release-candidates (e.g. `XXXX.release-1.15.0.rc0`)
-- run `tox -e news` to produce a new NEWS.txt file (this does a commit)
+- Create a branch for the release/candidate (e.g. ``XXXX.release-1.16.0``)
+- run tox -e news to produce a new NEWS.txt file (this does a commit)
 - create the news for the release
 
   - newsfragments/<ticket number>.minor
@@ -46,7 +70,7 @@ Create Branch and Apply Updates
 
 - manually fix NEWS.txt
 
-  - proper title for latest release ("Release 1.15.0" instead of "Release ...post1432")
+  - proper title for latest release ("Release 1.16.0" instead of "Release ...post1432")
   - double-check date (maybe release will be in the future)
   - spot-check the release notes (these come from the newsfragments
     files though so don't do heavy editing)
@@ -54,7 +78,7 @@ Create Branch and Apply Updates
 
 - update "relnotes.txt"
 
-  - update all mentions of 1.14.0 -> 1.15.0
+  - update all mentions of ``1.16.0`` to new and higher release version for example ``1.16.1``
   - update "previous release" statement and date
   - summarize major changes
   - commit it
@@ -63,12 +87,6 @@ Create Branch and Apply Updates
 
   - change the value given for `version` from `OLD.post1` to `NEW.post1`
 
-- update "CREDITS"
-
-  - are there any new contributors in this release?
-  - one way: git log release-1.14.0.. | grep Author | sort | uniq
-  - commit it
-
 - update "docs/known_issues.rst" if appropriate
 - Push the branch to github
 - Create a (draft) PR; this should trigger CI (note that github
@@ -94,10 +112,14 @@ they will need to evaluate which contributors' signatures they trust.
 - (all steps above are completed)
 - sign the release
 
-  - git tag -s -u 0xE34E62D06D0E69CFCA4179FFBDE0D31D68666A7A -m "release Tahoe-LAFS-1.15.0rc0" tahoe-lafs-1.15.0rc0
-  - (replace the key-id above with your own)
+  - git tag -s -u 0xE34E62D06D0E69CFCA4179FFBDE0D31D68666A7A -m "release Tahoe-LAFS-1.16.0rc0" tahoe-lafs-1.16.0rc0
+
+.. note:: 
+    - Replace the key-id above with your own, which can simply be your email if it's attached to your fingerprint.
+    - Don't forget to put the correct tag message and name. In this example, the tag message is "release Tahoe-LAFS-1.16.0rc0" and the tag name is ``tahoe-lafs-1.16.0rc0`` 
 
 - build all code locally
+
   - these should all pass:
 
     - tox -e py27,codechecks,docs,integration
@@ -114,8 +136,9 @@ they will need to evaluate which contributors' signatures they trust.
 - build tarballs
 
   - tox -e tarballs
-  - confirm it at least exists:
-  - ls dist/ | grep 1.15.0rc0
+  - Confirm that release tarballs exist by runnig: 
+
+    - ls dist/ | grep 1.16.0rc0
 
 - inspect and test the tarballs
 
@@ -124,12 +147,12 @@ they will need to evaluate which contributors' signatures they trust.
 
 - when satisfied, sign the tarballs:
 
-  - gpg --pinentry=loopback --armor --detach-sign dist/tahoe_lafs-1.15.0rc0-py2.py3-none-any.whl
-  - gpg --pinentry=loopback --armor --detach-sign dist/tahoe_lafs-1.15.0rc0.tar.gz
+  - gpg --pinentry=loopback --armor --detach-sign dist/tahoe_lafs-1.16.0rc0-py2.py3-none-any.whl
+  - gpg --pinentry=loopback --armor --detach-sign dist/tahoe_lafs-1.16.0rc0.tar.gz
 
 
 Privileged Contributor
------------------------
+======================
 
 Steps in this portion require special access to keys or
 infrastructure. For example, **access to tahoe-lafs.org** to upload