[VOL-5166] - docs.votlha.org: misc edits
overview/contributing.rst
overview/contributing/jira_tickets.rst
overview/contributing/patch_followup.rst
----------------------------------------
o Doc edits to improve clarity.
Change-Id: I14fe6371313205d146a3bf9a7ee83ca4c349d713
diff --git a/overview/contributing.rst b/overview/contributing.rst
index 768b878..1eadef4 100644
--- a/overview/contributing.rst
+++ b/overview/contributing.rst
@@ -74,29 +74,44 @@
`jenkins job <https://jenkins.opencord.org>`_.
Wait for job completion status before proceeding.
- - Job completion status will be sent to you asynchronously in email.
- - For direct monitoring `review comment history for your patch <https://gerrit.opencord.org/q/status:open+-is:wip>`_.
- - Search for `Jenkins Technical User <https://gerrit.opencord.org/c/voltha-docs/+/33952>`_ and click a job entry.
- - In the top grey navigation bar, following "Dashboard", click the test suite name to view the active job dashboard history `verify_voltha-docs_unit-test <https://jenkins.opencord.org/job/verify_voltha-docs_unit-test/>`_.
+ - Job status will be sent to you asynchronously in email at job completion.
+ - For direct monitoring :doc:`review gerrit Change Log<contributing/patch_followup>` for your patch.
- If testing fails please fix your patch with step 3 an then repeat 2 and 3, as necessary.
+ - If testing fails please fix your patch with step 3 then repeat 2 and 3 as needed.
**Passing CI verification is mandatory.**
+ To view accumulated job status:
+
+ - `navigate to a patch <https://gerrit.opencord.org/c/ci-management/+/34599>`_
+ - View "Submit requirements" in the top left.
+ - Verified ``+1 Jenkins Technical User`` will indicate SUCCESS.
+ - Verified ``-1 Jenkins Technical User`` will indicate FAILURE.
+
If the CI check does not start or fails and you believe the issue is
un-related to a changeset you can re-trigger by commenting on the
- patch with `recheck`.
+ patch with `recheck <https://docs.voltha.org/master/howto/code/pull_request.html#development-and-code-reviews>`_
If failures persist `ask for assistance <https://wiki.opennetworking.org/display/COM/VOLTHA>`_ in slack or a mailing list.
- 6. When comments are made to your patch please make the appropriate fixes and then
+ 6. When patch comments are offered please make the appropriate fixes and then
amend your commit with `git commit --amend` and re-upload to gerrit with `git review`.
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>`_
+ can give final review approval.
+
+ **All changes must acquire +2 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.
+ 8. A patch will be ready to submit a merge request when
+
+ - "Submit requirements" in the top left is showing:
+
+ - Code-Review: +2 approval (or 2 x +1 approval)
+ - Verified ``+1 Jenkins Technical User``
+
Versioning
++++++++++
diff --git a/overview/contributing/jira_tickets.rst b/overview/contributing/jira_tickets.rst
index ef97b75..1f372d7 100644
--- a/overview/contributing/jira_tickets.rst
+++ b/overview/contributing/jira_tickets.rst
@@ -6,17 +6,35 @@
- For large or multi-part features create a containing ticket with several
sub-tickets tracking individual features or problems.
- - Primary tracking ticket.
- - VOL-5125 - Tracking ticket for bbsim failures in jenkins vip job view.
+.. list-table:: Multi-part ticket with subtask
+ :widths: 10, 10, 40
+ :header-rows: 1
- - Sub-ticket(s)
- - VOL-5024 - bbsim unit test job reporting status=UNSTABLE
- - VOL-5157 - verify_bbsim_unit-test failures in history
- - VOL-5154 - Triage test failure in periodic-voltha-unitag-subscriber-tt-test-bbsim
+ * - Jira
+ - Type
+ - Problem
+ * - `VOL-5125 <https://jira.opencord.org/browse/VOL-5125>`_
+ - Epic
+ - Tracking ticket for bbsim failures in jenkins vip job view.
+ * - `VOL-5024 <https://jira.opencord.org/browse/VOL-5024>`_
+ - sub-task
+ - bbsim unit test job reporting status=UNSTABLE
+ * - `VOL-5157 <https://jira.opencord.org/browse/VOL-5157>`_
+ - sub-task
+ - verify_bbsim_unit-test failures in history
+ * - `VOL-5154 <https://jira.opencord.org/browse/VOL-5154>`_
+ - sub-task
+ - Triage test failure in periodic-voltha-unitag-subscriber-tt-test-bbsim
- Description - include relevant information
- Error messages
+
+ - Use preformatting to improve readability (else message becomes a run-on sentence).
+ - In ticket description click plus icon on the right side.
+ - Select preformatted
+ - Copy and patest text into the preformatted box to retain structure.
+
- Reproduction step(s) for problems
- Web URLs, links to jenkins job logs are very helpful.
diff --git a/overview/contributing/patch_followup.rst b/overview/contributing/patch_followup.rst
new file mode 100644
index 0000000..3c9334f
--- /dev/null
+++ b/overview/contributing/patch_followup.rst
@@ -0,0 +1,148 @@
+Pull request followup
+=====================
+
+Once a patch has been submitted gerrit can be used to track progress.
+
+Find your patch
+---------------
+
+| Begin by viewing the history for your patch in gerrit.
+| A patch can be accessed in a few different ways.
+
+Item of Note:
+
+- A Gerrit Change-Id is required to interact with a patch. This hashed
+ value will be distinct from the underlying git checksum used when
+ changes are stored in a repository.
+
+Capture commit message output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Gerrit commit hash and a URL are readily available in output.
+
+.. code-block:: shell-session
+ :linenos:
+ :emphasize-lines: 22
+
+ % git commit -F ../jira/5100
+ % git rebase
+ % git review --reviewers tux@onf.org
+
+ remote:
+ remote: Processing changes: (\)
+ remote: Processing changes: (|)
+ remote: Processing changes: (/)
+ remote: Processing changes: (-)
+ remote: Processing changes: (\)
+ remote: Processing changes: (|)
+ remote: Processing changes: (/)
+ remote: Processing changes: (-)
+ remote: Processing changes: new: 1 (\)
+ remote: Processing changes: refs: 1, new: 1 (\)
+ remote: Processing changes: refs: 1, new: 1 (\)
+ remote: Processing changes: refs: 1, new: 1, done
+ remote:
+ remote: SUCCESS
+ remote:
+ remote: https://gerrit.opencord.org/c/ci-management/+/34600 Disable jobs dependent on offline menlo-3 node [NEW]
+ fremote:
+ To ssh://gerrit.opencord.org:29418/ci-management.git
+ * [new reference] HEAD -> refs/for/master%topic=dev-joey
+
+.. list-table:: Git commit message
+ :widths: 20, 5, 60
+ :header-rows: 1
+
+ * - Id
+ - Line
+ - Description
+ * -
+ - 2
+ - Git commit hash
+ * - `34598 <https://gerrit.opencord.org/c/ci-management/+/34598>`_
+ - 10
+ - Gerrit URL for direct patch access
+ * -
+ - 14
+ -
+
+Git log
+^^^^^^^
+
+Gerrit Change-IDs are appended as the last line in a commit mesage.
+git log can be used to search for them.
+
+.. code-block:: shell-session
+ :linenos:
+ :emphasize-lines: 3,14
+
+ % git log --author="joey" | less
+
+ commit 23ce887c4cb3f98506536e00c58ffc8c2af16afe
+ Author: Joey Armstrong <joey@opennetworking.org>
+ Date: Thu Aug 24 09:46:22 2023 -0400
+
+ [VOL-5009] - Update release notes
+
+ release_notes/voltha_2.12.rst
+ -----------------------------
+ o Import Mahir(s) word doc containing tickets and descriptions.
+ o Reformat using a grid layout so tickets and description are aligned.
+
+ Change-Id: Ic8ca17f5923496731f88ce8918c9852d904ea066
+
+.. list-table:: Git log commit IDs
+ :widths: 20, 5, 60
+ :header-rows: 1
+
+ * - Id
+ - Line
+ - Description
+ * - 23ce887c4cb3f98506536e00c58ffc8c2af16afe
+ - 3
+ - Git commit hash
+ * - Ic8ca17f5923496731f88ce8918c9852d904ea066
+ - 14
+ - Gerrit Change-Id
+
+
+Patch lookup by Change-Id string
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you have a Change-Id value (~43 chars)
+
+- Change-Id: Ic8ca17f5923496731f88ce8918c9852d904ea066
+
+ - Visit the `Gerrit dashboard <https://gerrit.opencord.org/dashboard/self>`_
+ - Paste Change-Id into the search box at the top right
+ - Gerrit UI will navigate to the patch.
+
+Brute force patch lookup
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Visit `Gerrit dashboard open+is:wip <https://gerrit.opencord.org/q/status:open+-is:wip>`_
+
+ - View all open/unmerged patches
+ - Scroll down through the list until something of interest is found.
+ - Under the # column (2nd column on left hand side) right click and open to view the patch.
+ - For example: `repo:voltha-system-tests <https://gerrit.opencord.org/c/voltha-system-tests/+/33380>`_
+
+Patch history and jenkins jobs
+------------------------------
+
+While viewing a patch (`repo:voltha-system-tests <https://gerrit.opencord.org/c/voltha-system-tests/+/33380>`_)
+scroll down to the 'Change Log' section at the bottom.
+| Line items represent historical comments, code review messages and
+processed job status.
+
+Entries prefixed with ``Jenkins Technical User`` contain jenkins job
+information. Jenkins pipeline jobs are constructed by performing
+several atomic tasks each of which will generate a log with status.
+
+To view job logs click on an entry to expand (Verified +1, 4th entry from
+the bottom) to view a set of clickable jenkins URLs.
+
+- `Patch 33380 <https://gerrit.opencord.org/c/voltha-system-tests/+/33380>`_
+ - `verify_voltha-system-tests_unit-test <https://jenkins.opencord.org/job/verify_voltha-system-tests_unit-test>`_ : SUCCESS
+ - `verify_voltha-system-tests_licensed <https://jenkins.opencord.org/job/verify_voltha-system-tests_licensed>`_ : SUCCESS
+ - `verify_voltha-system-tests_sanity-test <https://jenkins.opencord.org/job/verify_voltha-system-tests_sanity-test>`_ : FAILED