summaryrefslogtreecommitdiff
path: root/docs/contributing/documentation.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/contributing/documentation.rst')
-rw-r--r--docs/contributing/documentation.rst95
1 files changed, 60 insertions, 35 deletions
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
index 99e1fab7..601688ee 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -14,61 +14,81 @@ guid how to do so.
you open up a Phabricator_ task prior to submitting a Pull-Request to the
documentation.
-Git Workflow
-------------
+Forking Workflow
+----------------
+The Forking Workflow is fundamentally different than other popular Git
+workflows. Instead of using a single server-side repository to act as the
+"central" codebase, it gives every developer their own server-side repository.
+This means that each contributor has not one, but two Git repositories: a
+private local one and a public server-side one.
-Updates to our documentation should be delivered by a GitHub pull-request. In
-order to create a pull-request you need to fork our documentation code first.
-This requires you already have a GitHub account.
+The main advantage of the Forking Workflow is that contributions can be
+integrated without the need for everybody to push to a single central
+repository. Developers push to their own server-side repositories, and only the
+project maintainer can push to the official repository. This allows the
+maintainer to accept commits from any developer without giving them write
+access to the official codebase.
-* Fork the project on GitHub https://github.com/vyos/vyos-documentation/fork
+.. node:: Updates to our documentation should be delivered by a GitHub
+ pull-request. This requires you already have a GitHub account.
+
+* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork
* Clone fork to local machine
-* Change to your new local directory ``vyos-documentation``
+* Change to your new local directory ``$ cd vyos-documentation``
* Create new branch for your work, use a descriptive name of your work:
``$ git checkout -b fix-vxlan-typo``
-* Make all your changes - please keep out commit rules in mind
- (:ref:`prepare_commit`). This mainly applies to a proper commit message
- describing your change. Please check the documentation if you aren't familiar
- with Sphinx-doc_ or reStructuredText_.
+* Make all your changes - please keep our commit rules in mind
+ (:ref:`prepare_commit`). This mainly applies to proper commit messages
+ describing your change (how and why). Please check out the documentation of
+ Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used
+ for writing our docs.
+* Check your changes by locally building the documentation ``$ make html``.
+ Sphinx will build the html files in the ``docs/_build`` folder. We provide
+ you with a Docker container for an easy to use user experience. Check the
+ README.md_ file of this repository.
-* Check your changes by locally building the documentation ``$ make html``
- Sphinx will build the html files in the ``docs/_build`` folder
+* View modified files by calling ``$ git status``. You will get an overview of
+ all files modified by you. You can add individual files to the Git Index in
+ the next step.
-* Add modified files to Git index ``$ git add path/to/filname`` or add all
- unstaged files ``$ git add .``
+* Add modified files to Git index ``$ git add path/to/filename`` or add all
+ unstaged files ``$ git add .``. All files added to the Git index will be part
+ of you following Git commit.
-* Commit your changes ``$ git commit -m "vxlan: rework CLI syntax"``
+* Commit your changes ``$ git commit -v`` - your configured editor will now ne
+ launched where you can type in a commit message. Again please make yourself
+ comfortable with out rules (:ref:`prepare_commit`).
-* Push your commits to your GitHub project: ``$ git push -u origin
- fix-vxlan-typo``
+* Push your commits to your GitHub project: ``$ git push -u origin foo-branch``
* Submit pull-request. In GitHub visit the main repository and you should
see a banner suggesting to make a pull request. Fill out the form and
describe what you do.
* Once pull resquests have been approved, you may want to locally update
- your forked repository too. First you'll have to add the remote upstream
- repository. ``$ git remote add upstream
- https://github.com/vyos/vyos-documentation.git``
+ your forked repository too. First you'll have to add a second remote
+ called `upstream` which points to our main repository. ``$ git remote add
+ upstream https://github.com/vyos/vyos-documentation.git``
Check your configured remote repositories:
.. code-block:: none
$ git remote -v
- origin https://github.com/YOUR_USERNAME/vyos-documentation.git (fetch)
- origin https://github.com/YOUR_USERNAME/vyos.documentation.git (push)
+ origin https://github.com/<username>/vyos-documentation.git (fetch)
+ origin https://github.com/<username>/vyos.documentation.git (push)
upstream https://github.com/vyos/vyos-documentation.git (fetch)
upstream https://github.com/vyos/vyos-documentation.git (push)
- Your remote repo on Github is called Origin, while the original repo you
- have forked is called Upstream. Now you can locally update your forked repo.
+ Your remote repo on Github is called ``origin``, while the original repo you
+ have forked is called ``upstream``. Now you can locally update your forked
+ repo.
.. code-block:: none
@@ -76,9 +96,8 @@ This requires you already have a GitHub account.
$ git checkout master
$ git merge upstream/master
- If you want to update your fork on GitHub, too use the following:
- ``$ git push origin master``
-
+* If you want to update your fork on GitHub, too use the following: ``$ git
+ push origin master``
Style Guide
-----------
@@ -129,15 +148,15 @@ system numbers for the documentation:
Please don't use other public address space.
-Specific Sphinx-doc Markup
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Custom Sphinx-doc Markup
+^^^^^^^^^^^^^^^^^^^^^^^^
-When documenting CLI commands use the ``.. cfgcmd::`` directive for
-the configuration mode and the ``.. opcmd::`` directive for operational mode
-commands.
-Under the command a short exlaination should be provide.
+When documenting CLI commands use the ``.. cfgcmd::`` directive for all
+configuration mode commands. When documenting operational level command use
+the ``.. opcmd::`` directive. An explanation of the described command should
+be added below this statement.
-Example:
+**Example**
.. code-block:: none
@@ -145,6 +164,12 @@ Example:
Display all known ARP table entries spanning accross all interfaces
+ .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa
+
+ This will configure a static ARP entry always resolving `192.0.2.100` to
+ `00:53:27:de:23:aa`.
+
.. _Sphinx-doc: https://www.sphinx-doc.org
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _Phabricator: https://phabricator.vyos.net
+.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md