blob: 73096ee508bf63f0f49fa4f31b7dea292a9fbc8f [file] [log] [blame]
Joey Armstrong924f3cb2023-06-05 15:21:51 -04001Quickstart Guide: Editing
2=========================
3
4Intent
5------
6
7This quickstart guide decribes how to modify and commit changes that will
Joey Armstrong449ce7a2023-07-18 18:32:24 -04008be visible on https://docs.voltha.org.
Joey Armstrong924f3cb2023-06-05 15:21:51 -04009
10Clone repo:voltha-docs
11----------------------
12
13.. code:: bash
14
15 # Clone repo:voltha-docs
16 git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
17
18 # Create a developer branch
19 git checkout -b dev-joey
20
Joey Armstrongb8a1e052023-08-07 09:32:53 -040021.. code-block:: shell-session
Joey Armstrongc5427b22023-08-15 08:55:33 -040022 :linenos:
23 :emphasize-lines: 2
Joey Armstrong924f3cb2023-06-05 15:21:51 -040024
25 # Clone repo:voltha-docs
26 git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
27
28 # Create a developer branch
29 git checkout -b dev-joey
30
31Repositories:
Joey Armstrongb8a1e052023-08-07 09:32:53 -040032[`gerrit <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_],
33[`github <https://github.com/opencord/voltha-docs>`_]
Joey Armstrong924f3cb2023-06-05 15:21:51 -040034
Joey Armstrongb8a1e052023-08-07 09:32:53 -040035.. code-block:: shell-session
Joey Armstrongc5427b22023-08-15 08:55:33 -040036 :linenos:
37 :emphasize-lines: 2,5
Joey Armstrong924f3cb2023-06-05 15:21:51 -040038
39 # Clone repo:voltha-docs
40 git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
41
42 # Create a developer branch
43 git checkout -b dev-joey
44
45Interactive development
46-----------------------
47
Joey Armstrongb8a1e052023-08-07 09:32:53 -040048.. code-block:: shell-session
Joey Armstrong924f3cb2023-06-05 15:21:51 -040049 :caption: Launch a browser for viewing local edits
Joey Armstrongc5427b22023-08-15 08:55:33 -040050 :linenos:
51 :emphasize-lines: 4
Joey Armstrong924f3cb2023-06-05 15:21:51 -040052
53 cd voltha-docs
54 make reload
55
56- source edit: modify reStructuredText (RST) sources
57- Modify content to taste
58
59Invoke checkin tests locally
60----------------------------
61
Joey Armstrongb8a1e052023-08-07 09:32:53 -040062.. code-block:: shell-session
Joey Armstrongc5427b22023-08-15 08:55:33 -040063 :linenos:
64 :emphasize-lines: 3
Joey Armstrong924f3cb2023-06-05 15:21:51 -040065
66 cd voltha-docs
67 make sterile
68 make test
69
70.. list-table:: makefile targets for testing
71 :widths: 30,50
72 :header-rows: 2
73
74 * - make target
75 - Description
76 * -
77 -
78 * - make test
79 - Kitchen sink target: invokes all checkin tests (make lint linkcheck)
80 * - make lint
81 - Syntax check by source: rst, python
82 * - make linkcheck
83 - Verify URLs inlined within rst files are valid
84
Joey Armstrongb8a1e052023-08-07 09:32:53 -040085Document and commit changes for git log
86---------------------------------------
Joey Armstrong924f3cb2023-06-05 15:21:51 -040087
Joey Armstrongb8a1e052023-08-07 09:32:53 -040088.. code-block:: shell-session
Joey Armstrong924f3cb2023-06-05 15:21:51 -040089
Joey Armstrongb8a1e052023-08-07 09:32:53 -040090 # Commit message:
91 # - symmarize changes with jira ticket linkage.
92 # - jenkins will update jira ticket with status when a job is run.
Joey Armstrong924f3cb2023-06-05 15:21:51 -040093 echo '[VOL-XXXX] update voltha.docs' > commit_message
94
95 # Commit message: Capture list of modified files
96 git status >> commit_message
97
98 # Commit message: Capture source diffs
99 git diff >> commit_message
100
101 # Summarize changes for git log
102 $EDIT commit_message
103
104 # git add <modified files>
105
106 # Commit changes to revision control
107 git commit -F commit_message
108
109 # Rebase your sandbox, merge branch=master into branch=dev-joey
110 ... git rebase documentation URL needed here ...
111
112 # Create a patch and request a code review
113 git review --reviewers email1 email2 email3
114
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400115
Joey Armstrongb8a1e052023-08-07 09:32:53 -0400116Sample commit message
117---------------------
118
119.. code-block:: shell-session
120
121 # Line 1: Commit message summary for git log
122 # - 50cpl max else a warning displayed.
123 # - jira tickets are updated by jenkins as jobs are run.
124 [VOL-xxxx] - Update voltha docs
125
126 # Optional extra jira tickets related to the patch
127 [VOL-yyyy]
128 [VOL-zzzz]
129
130 jjb/pipeline/voltha/master/bbsim-tests.groovy
131 vars/installKind.groovy
132 vars/installKind.sh
133 --------------------------------------------------
134 o Refactor inlined installer logic into a standalone script for reuse.
135 o Updated voltha-system-tests makefiles, added a target to install
136 the kind command (centrally, consistent version!) similar to kail.
137
138Extra credit
139------------
140
141- Update `copyright notice <https://github.com/joey-onf/copyright/blob/origin/master/notice>`_ in the year files are modified (`repo:copyright <https://github.com/joey-onf/copyright>`_).
142
143- Syntax checking source
144
145.. code-block:: shell-session
146
147 make help | grep lint
148 make lint
149
150- make test
151
152.. code-block:: shell-session
153
154 make test # Invoke: make lint linkcheck
155
156- Warning triage and cleanup.
157
158.. code-block:: shell-session
Joey Armstrong924f3cb2023-06-05 15:21:51 -0400159
160 make sterile
161 make html 2>&1 | sed -e 's/WARNING/\nWARNING/g' | less --ignore-case --hilite-search '/WARNING'
Joey Armstrong704dd6d2023-08-24 08:01:47 -0400162
163Caveat(s)
164---------
165
166- An overnight process is responsible for publishing repo:voltha-docs
167 edits on https://docs.voltha.org. Due to this delay it can take
168 up to 24 hours before changes become visible on the website.