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.