Document commit message syntax, job directives, etc.  Decorate as a cross-reference page to encourage reuse

Change-Id: I3f3b12cfd6cd3dd10a91b28a36f4e487fa25f464
diff --git a/VERSION b/VERSION
index d1666bf..ea41b64 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.12.5.1-dev2
+2.12.5.1-dev3
diff --git a/howto/code/commit-message.rst b/howto/code/commit-message.rst
new file mode 100644
index 0000000..f18f8b3
--- /dev/null
+++ b/howto/code/commit-message.rst
@@ -0,0 +1,79 @@
+.. _pull-request--commit-message:
+
+Repository commit message
+=========================
+
+- First line in a commit message is special.
+- 50 cpl max to avoid complaints about length.
+- Mention a jira ticket (VOL-xxxx) and the ticket will receive status updates from jenkins.
+
+.. code:: bash
+
+   [VOL-5048] - Build and deploy for VOLTHA v2.12 release.
+
+   api/pom.xml
+   app/pom.xml
+   pom.xml
+   -----------
+     o Update copyright notice to span CCYY.
+     o Update maven plugins spotbugs and findsecbugs.
+     o Update sadis component to vX.Y.Z
+
+   pkg/*
+   Makefile
+   ----------
+     o Update copyright notice.
+     o Run gofmt -s -w on all golang sources.
+
+   VERSION
+   -------
+     o Increment version string to non-dev for release.
+
+   Job Directives
+   --------------
+   verify_{project}_licensed
+   verify_{project}_tag-collision
+   verify_{project}_unit-test
+   verify_{project}_sanity-test
+
+   hardware test functional tests
+   voltha test openonu multiolt
+   voltha 2.8 test openonu multiolt
+
+git commit ...
+--------------
+
+- A commit message can be constructed using either
+
+  - -F <file>
+  - --message="inlined text"
+
+.. code:: bash
+
+   $ vi commit.txt
+   $ git add *stuff*
+   $ git commit --F ./commit.txt
+   # appropriate git rebase command
+   $ git review --reviewers tux@onf.org foo@onf.org bar@onf.org
+
+Commit Message: extra credit
+++++++++++++++++++++++++++++
+
+Additional commit message directives are available that will augment tasks
+performed by a job.  Additional test suites can be requested for a job run
+by including tokens found here.
+
+`Tokens
+<https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_ can be embedded within a commit message to enable running additional test suites as part of jenkins validation.
+
+Troubleshooting:
+++++++++++++++++
+
+There have been a few reports of additional testing not beeing initiated
+by a commit.  If you encounter this behavior visit the
+`VOLTHA jira site <https://jira.opencord.org/secure/Dashboard.jspa>`_
+and open a trouble ticket detailing the changeset URL or a repository
+and commit message text.
+
+Commit hooks can be repository specific and may need to be
+deployed/enabled/updated to support requestd functionality.
diff --git a/howto/code/index.rst b/howto/code/index.rst
index 685dc2a..998109c 100644
--- a/howto/code/index.rst
+++ b/howto/code/index.rst
@@ -4,6 +4,7 @@
 .. toctree::
    :maxdepth: 2
 
+   commit-message
    job-failures
    linting
    pull_request
diff --git a/howto/code/pull_request.rst b/howto/code/pull_request.rst
index 677e4e2..f3c1c58 100644
--- a/howto/code/pull_request.rst
+++ b/howto/code/pull_request.rst
@@ -1,23 +1,24 @@
+.. _pull-request-see-also:
+
 VOLTHA project repositories
 ===========================
 
 Development and code reviews:
 -----------------------------
 
-Commit decorations:
-+++++++++++++++++++
+:ref:`Commit message syntax <pull-request--commit-message>`
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-`Tokens
-<https://docs.voltha.org/master/testing/voltha_test_automation.html#per-patchset-verification-jobs>`_ can be embedded within a commit message to enable running additional test suites as part of jenkins validation.
+Job directives: recheck
+-----------------------
 
-NOTE:
-+++++
-There have been a few reports of testing not being triggered by a commit.
-If you encounter this behavior visit the VOLTHA jira site and open a ticket.
-Commit hooks can be repository specific and may need to be deployed/enabled to support functionality.
+If the CI check did not launch or failed and you believe the issue is
+unrelated to your patch/changeset you can re-trigger the job by commenting
+on the patch with *recheck*.
 
-- :vol-jira:``
-- Include gerrit URL for your changeset.
-- Target repository name/url.
-- What tests or suites were expected that were not exercised.
+- Visit gerrit:  https://gerrit.opencord.org/c/bbsim/+/34384
+- Click the pencil icon in the top left by reviewers.
+- Comment/description text: recheck
 
+It may take a little while to run dependent on queue size but this token will
+initiate re-running job phases for a patch.
diff --git a/howto/release/preparation.rst b/howto/release/preparation.rst
index 2c515d0..fe41e28 100644
--- a/howto/release/preparation.rst
+++ b/howto/release/preparation.rst
@@ -5,8 +5,15 @@
 ------------
 As release date approaches and development slows visit the `jira versions dashboard <https://jira.opencord.org/projects/VOL?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&status=unreleased>`_.
 
-- Create a new dashboard for the future release candidate.
+- Create a new/empty dashboard for the future release candidate.
+
+  - Click in the ``Version name`` box and type in VOLTHA-(X.Y)++ for the next release.
+  - Enter start/end dates if known, they should overlap with the last release.
+
 - Visit the current released candidate version and move all unresolved tickets into the future desktop.
+
+  - TSTs may want to review unresolved tickets for release notes content for partially completed work.
+
 - On release day click the [Release] button to close out the desktop.
 
 Confluence
diff --git a/overview/contributing.rst b/overview/contributing.rst
index f774e18..4b892d8 100644
--- a/overview/contributing.rst
+++ b/overview/contributing.rst
@@ -51,15 +51,20 @@
     * - Command
       - Description
     * - `make lint <https://docs.voltha.org/master/howto/code/linting.html>`_
-      - Syntax check source for problems
+      - Syntax check source for problems (lint, lint-shelcheck, lint-doc8)
     * - make sca
       - Static Code Analysis
+    * - make build
+      - Assemble, compile, generate, link, ...
     * - make test
       - Invoke VOLTHA test suite(s)
     * - make help
-      - Show available targets, bulk source cleanup needed for `make lint` to check everything by default.
+      - Show available targets: make help | grep lint
 
- 4. Submitting your patch will initiate a `jenkins job <https://jenkins.opencord.org>`_ to validate changes.
+ 4. :ref:`Commit message syntax and testing directives <pull-request--commit-message>`
+
+ 5. Submitting your patch will initiate a validation
+    `jenkins job <https://jenkins.opencord.org>`_.
     Wait for job completion status before proceeding.
 
     - Job completion status will be sent to you asynchronously in email.
@@ -77,10 +82,10 @@
 
     If failures persist `ask for assistance <https://wiki.opennetworking.org/display/COM/VOLTHA>`_ in slack or a mailing list.
 
- 5. When comments are made to your patch please make the appropriate fixes and then
+ 6. When comments are made to your patch please make the appropriate fixes and then
     amend your commit with `git commit --amend` and re-upload to gerrit with `git review`.
 
- 6. Await review. Everyone can comment on code changes, but only Core contributors
+ 7. Await review. Everyone can comment on code changes, but only Core contributors
     can give final review approval. **All changes must get at least one
     approval**. Join one of the `communication channels <https://wiki.opennetworking.org/display/COM/VOLTHA>`_
     to request a review or to bring additional attention to your patch.