Skip to content

Commit

Permalink
improve documentation how-to and create PR template
Browse files Browse the repository at this point in the history
  • Loading branch information
@rebortg
rebortg committed Mar 7, 2024
1 parent f3d8f9f commit f35a3ba
Show file tree
Hide file tree
Showing 2 changed files with 141 additions and 110 deletions.
22 changes: 22 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<!-- All PR should follow this template to allow a clean and transparent review -->
<!-- Text placed between these delimiters is considered a comment and is not rendered -->

## Change Summary
<!--- Provide a general summary of your changes in the Title above -->

## Related Task(s)
<!-- optional: Link related Tasks on Phabricator. -->
* https://vyos.dev/Txxxx

## Related PR(s)
<!-- optional: Link here any PRs in other repositories that are related to this PR -->

## Backport
<!-- optional: the PR should backport to this documentation branch -->



## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [ ] I have read the [**CONTRIBUTING**](https://github.com/vyos/vyos-documentation/blob/master/CONTRIBUTING.md) document
229 changes: 119 additions & 110 deletions docs/documentation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,25 +18,23 @@ guide how to do so.
documentation.

VyOS documentation is written in reStructuredText and generated to Read the Docs
pages with Sphinx, as per the Python tradition, as well as PDF files for offline
use through LaTeX. We welcome all sorts of contributions to the documentation.
pages with Sphinx, as per the Python tradition. We welcome all sorts of
contributions to the documentation.
Not just new additions but also corrections to existing documentation.

The documentation source is kept in the Git repository at
https://github.com/vyos/vyos-documentation and you can follow the instructions
in the README.md_ to build and test your changes.

You can either install Sphinx (and TeX Live for PDF output) and build the
documentation locally, or use the Dockerfile_ to build it in a container.
You can either install Sphinx and build the documentation locally,
or use the Dockerfile_ to build it in a container.

Guidelines
==========

There are a few things to keep in mind when contributing to the
documentation, for the sake of consistency and readability.

Take a look at the :doc:`/documentation` page for an intricate explanation
of the documentation process.

The following is a quick summary of the rules:

Expand All @@ -54,94 +52,73 @@ And finally, remember that the reStructuredText files aren't
exclusively for generating HTML and PDF. They should be human-readable
and easily perused from a console.

Forking Workflow
================
Page content
============

The Forking Workflow is fundamentally different from 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.
All RST files must follow the same TOC Level syntax and have to start with

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.
.. code-block::
.. note:: Updates to our documentation should be delivered by a GitHub
pull-request. This requires you already have a GitHub account.
#####
Title
#####
* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork
The configuration mode folder and the articles cover the specific level of
the commands. The exact level depends on the command. This should provide
stability for URLs used in the forum or blogpost.

* Clone fork to local machine, then change to that directory
``$ cd vyos-documentation``
For example:

* Install the requirements ``$ pip install -r requirements.txt``
(or something similar)
* ``set firewall zone`` is written in ``firewall/zone.rst``
* ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst``

* Create a new branch for your work, use a descriptive name of your work:
``$ git checkout -b <branch-name>``
In the configuration part of the page, all possible configuration options
should be documented. Use ``.. cfgcmd::`` described above.

* 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. Additional directives how to write in RST can be
obtained from reStructuredTextDirectives_.
Related operation command must be documented in the next part of the article.
Use ``::opcmd..`` for these commands.

* Check your changes by locally building the documentation ``$ make livehtml``.
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.
Each page must contain the following parts:

* 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.
1. Theoretical information
--------------------------

* 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.
Theoretical information required for users to understand the next document sections:

* Commit your changes with the message, ``$ git commit -m "<commit message>"``
or use ``$ git commit -v`` to have your configured editor launched. You can
type in a commit message. Again please make yourself comfortable without
rules (:ref:`prepare_commit`).
- a simple explanation of what is this page about, why or when it is required to be used
- references to standards, RFCs

* Push commits to your GitHub project: ``$ git push -u origin <branch-name>``
2. Configuration description
----------------------------

* 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.
Describe CLI items related to the service or use case. Each config line
or section must be explained, using information provided in the 1st part
of the page.

* Once pull requests 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``
3. Configuration examples
-------------------------

Check your configured remote repositories:
Practical examples of the service or use case configuration. They must
contain topology maps (if applicable) and short descriptions.

.. code-block:: none
4. Known issues
---------------

$ 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)
This section must contain a list of:

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.
- known issues or potential problems for the service or use case
- workarounds for known issues (if any exist)

.. code-block:: none
5. Debugging
------------

Described procedures for debugging a service:

- how to collect logs or other debugging information (like `show` commands output)
- how to read and what to search for in logs and collected information
- what are indicators of good and bad states in debugging outputs

$ git fetch upstream
$ git checkout master
$ git merge upstream/master

* If you also want to update your fork on GitHub, use the following: ``$ git
push origin master``

Style Guide
===========
Expand Down Expand Up @@ -381,63 +358,95 @@ URL. This is heavily used in the :ref:`release-notes` section.
* :vytask:`T1605` Fixed regression in L2TP/IPsec server
* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly
Page content
------------
The documentation has 3 different types of pages. The same kind of pages must
have the same structure to achieve a recognition factor.
Forking Workflow
================

All RST files must follow the same TOC Level syntax and have to start with
The Forking Workflow is fundamentally different from 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.

.. code-block::
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.

#####
Title
#####
.. note:: Updates to our documentation should be delivered by a GitHub
pull-request. This requires you already have a GitHub account.

Configuration mode pages
^^^^^^^^^^^^^^^^^^^^^^^^
* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork

The configuration mode folder and the articles cover the specific level of
the commands. The exact level depends on the command. This should provide
stability for URLs used in the forum or blogpost.
* Clone fork to local machine, then change to that directory
``$ cd vyos-documentation``

For example:
* Install the requirements ``$ pip install -r requirements.txt``
(or something similar)

* ``set firewall zone`` is written in ``firewall/zone.rst``
* ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst``
* Create a new branch for your work, use a descriptive name of your work:
``$ git checkout -b <branch-name>``

The article starts with a short introduction about the command or the
technology. Please include some helpful links or background information.
* 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. Additional directives how to write in RST can be
obtained from reStructuredTextDirectives_.

An optional section follows. Some commands have requirements like compatible
hardware (e.g. Wifi) or some commands you have to set before. For
example, it is recommended to set a route-map before configuring BGP.
* Check your changes by locally building the documentation ``$ make livehtml``.
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.

In the configuration part of the page, all possible configuration options
should be documented. Use ``.. cfgcmd::`` described above.
* 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.

Related operation command must be documented in the next part of the article.
Use ``::opcmd..`` for these commands.
* 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.

If there some troubleshooting guides related to the commands. Explain it in the
next optional part.
* Commit your changes with the message, ``$ git commit -m "<commit message>"``
or use ``$ git commit -v`` to have your configured editor launched. You can
type in a commit message. Again please make yourself comfortable without
rules (:ref:`prepare_commit`).

Operation mode pages
^^^^^^^^^^^^^^^^^^^^
* Push commits to your GitHub project: ``$ git push -u origin <branch-name>``

Operation mode commands that do not fit in a related configuration mode command
must be documented in this part of the documentation.
* 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.

General concepts for troubleshooting and detailed process descriptions belong
here.
* Once pull requests 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``

Anything else
^^^^^^^^^^^^^
Check your configured remote repositories:

Anything else that is not a configuration or an operation command has no
predefined structure.
.. 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 also want to update your fork on GitHub, use the following: ``$ git
push origin master``

.. stop_vyoslinter
Expand Down

0 comments on commit f35a3ba

Please sign in to comment.