1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
.. _documentation:
Documentation
=============
As most software projects we also have a lack in documentation. We encourage
every VyOS user to help us improve our documentation. This will not only be
beneficial for you (when reading something up) but also for the whole world.
If you are willing to contribute to our documentation this is the definite
guide how to do so.
.. note:: In contrast to submitting code patches, there is no requirement that
you open up a Phabricator_ task prior to submitting a Pull-Request to the
documentation.
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.
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.
.. note:: 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 ``$ 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 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.
* 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/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 -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 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 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/<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.
.. code-block:: none
$ git fetch upstream
$ git checkout master
$ git merge upstream/master
* If you want to update your fork on GitHub, too use the following: ``$ git
push origin master``
Style Guide
-----------
Sections
^^^^^^^^
We use the following syntax for Headlines.
.. code-block:: none
#####
Parts
#####
********
Chapters
********
Sections
========
Subsections
-----------
Subsubsections
^^^^^^^^^^^^^^
Paragraphs
""""""""""
Address space
^^^^^^^^^^^^^
Note the following RFCs (:rfc:`5737`, :rfc:`3849`, :rfc:`5389` and
:rfc:`7042`), which describe the reserved public IP addresses and autonomous
system numbers for the documentation:
* ``192.0.2.0/24``
* ``198.51.100.0/24``
* ``203.0.113.0/24``
* ``2001:db8::/32``
* 16bit ASN: ``64496 - 64511``
* 32bit ASN: ``65536 - 65551``
* Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF``
* Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF``
Please don't use other public address space.
Custom Sphinx-doc Markup
^^^^^^^^^^^^^^^^^^^^^^^^
When writing the documentation custom commands have been developed. Please
make yourself comfortable with those commands as this eases the way we
render the documentation.
cfgcmd
""""""
When documenting CLI commands use the ``.. cfgcmd::`` directive for all
configuration mode commands. An explanation of the described command should be
added below this statement.
With those custom commands it will be possible to render them in a more
descriptive way in the resulting HTML/PDF manual.
.. code-block:: none
.. 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`.
For a inline configuration level command use ``:cfgcmd:``
.. code-block:: none
:cfgcmd:`set interface ethernet eth0`
opcmd
"""""
When documenting operational level command use the ``.. opcmd::`` directive.
An explanation of the described command should be added below this statement.
With those custom commands it will be possible to render them in a more
descriptive way in the resulting HTML/PDF manual.
.. code-block:: none
.. opcmd:: show protocols static arp
Display all known ARP table entries spanning across all interfaces
For a inline operational level command use ``:opcmd:``
.. code-block:: none
:opcmd:`add system image`
vytask
""""""
When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup
command called ``vytask`` which automatically renders to a proper Phabricator
URL. This is heavily used in the :ref:`release-notes` section.
.. code-block:: none
* :vytask:`T1605` Fixed regression in L2TP/IPsec server
* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly
.. _Sphinx-doc: https://www.sphinx-doc.org
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md
.. include:: ../common-references.rst
|
