blob: 25743fed2095cfc056f8860332edd29f52205bd6 [file] [log] [blame]
Quickstart Guide: Editing
=========================
Intent
------
This quickstart guide decribes how to modify and commit changes that will
be visible on http://docs.voltha.org.
Clone repo:voltha-docs
----------------------
.. code:: bash
# Clone repo:voltha-docs
git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
# Create a developer branch
git checkout -b dev-joey
.. code-block: shell-session
:linenos: 2
# Clone repo:voltha-docs
git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
# Create a developer branch
git checkout -b dev-joey
Repositories:
`gerrit <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_
`github <https://github.com/opencord/voltha-docs>`_
.. code-block: shell-session
:linenos: 2,5
# Clone repo:voltha-docs
git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
# Create a developer branch
git checkout -b dev-joey
Interactive development
-----------------------
.. code-block: shell-session
:caption: Launch a browser for viewing local edits
:linenos: 4
cd voltha-docs
make reload
- source edit: modify reStructuredText (RST) sources
- Modify content to taste
Invoke checkin tests locally
----------------------------
.. code-block: shell-session
:linenos: 3
cd voltha-docs
make sterile
make test
.. list-table:: makefile targets for testing
:widths: 30,50
:header-rows: 2
* - make target
- Description
* -
-
* - make test
- Kitchen sink target: invokes all checkin tests (make lint linkcheck)
* - make lint
- Syntax check by source: rst, python
* - make linkcheck
- Verify URLs inlined within rst files are valid
Document and commit changes for ``git log``
-------------------------------------------
.. code-block: shell-session
:linenos:
# Commit message: Line 1 symmarize changes with jira ticket linkage.
echo '[VOL-XXXX] update voltha.docs' > commit_message
# Commit message: Capture list of modified files
git status >> commit_message
# Commit message: Capture source diffs
git diff >> commit_message
# Summarize changes for git log
$EDIT commit_message
# git add <modified files>
# Commit changes to revision control
git commit -F commit_message
# Rebase your sandbox, merge branch=master into branch=dev-joey
... git rebase documentation URL needed here ...
# Create a patch and request a code review
git review --reviewers email1 email2 email3
Extra credit
-------------------------------------------
.. code-block: shell-session
make sterile
make html 2>&1 | sed -e 's/WARNING/\nWARNING/g' | less --ignore-case --hilite-search '/WARNING'