summaryrefslogtreecommitdiff
path: root/docs/contributing
diff options
context:
space:
mode:
authorRobert Göhler <github@ghlr.de>2021-01-24 22:14:00 +0100
committerGitHub <noreply@github.com>2021-01-24 22:14:00 +0100
commitc25c40dfa96dfeb022b203280c607c1f1835417b (patch)
treeed05f81d48c65639e621ee3a067f435cb204ea9e /docs/contributing
parentce9f2016218f0c162bd48457a41a18db15e52749 (diff)
downloadvyos-documentation-c25c40dfa96dfeb022b203280c607c1f1835417b.tar.gz
vyos-documentation-c25c40dfa96dfeb022b203280c607c1f1835417b.zip
Migrate new file structure to crux (#435)
* order workflows and add submodule * rename gitmodules file * delete docs/.gitignore * add vyos custom linter * correct __pycache__ in gitignore * add test-coverage.py * move draw.io folder * arrange changelog, install history and about * arrange: firewall * arrange: highavailability * arrange: loadbalancing * arrange: nat * arrange: services * sort configexamples and configuration interfaces * wireles: rename wireless * rearrange: Protocols and Policy * rearrange: Firewall and Zone Policy * rearrange: Interfaces * rearrange: Interfaces * rearrange: dynamic DNS * hostinfo: add page to index * rearrange: appendix * venv: add Pipfile * rearrange: contributing * index: remove debugging * rearrange: fix all figure and refs * rearrange: commandtree * fix: cli, openvpn, install headline level * protocols: change headline * firewall: move mss clamping * ip: separate ipv4 and ipv6 * arp: move to static page * igmp: rename multicast page * Update to year 2021
Diffstat (limited to 'docs/contributing')
-rw-r--r--docs/contributing/documentation.rst175
-rw-r--r--docs/contributing/index.rst13
-rw-r--r--docs/contributing/issues-features.rst (renamed from docs/contributing/issues_features.rst)0
3 files changed, 13 insertions, 175 deletions
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
deleted file mode 100644
index 40edf750..00000000
--- a/docs/contributing/documentation.rst
+++ /dev/null
@@ -1,175 +0,0 @@
-.. _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
-benefical four you (when reading something up) but also for the whole world.
-
-If you are willing to contribute to our documentation this is the definate
-guid 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 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**
-
-.. code-block:: none
-
- .. opcmd:: show protocols static arp
-
- 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
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
new file mode 100644
index 00000000..8dd81d60
--- /dev/null
+++ b/docs/contributing/index.rst
@@ -0,0 +1,13 @@
+############
+Contributing
+############
+
+.. toctree::
+ :maxdepth: 2
+
+ issues-features
+ development
+ vyos_cli
+ coding_guidelines
+ upstream-packages
+ build-vyos \ No newline at end of file
diff --git a/docs/contributing/issues_features.rst b/docs/contributing/issues-features.rst
index 02de2df6..02de2df6 100644
--- a/docs/contributing/issues_features.rst
+++ b/docs/contributing/issues-features.rst