From c25c40dfa96dfeb022b203280c607c1f1835417b Mon Sep 17 00:00:00 2001 From: Robert Göhler Date: Sun, 24 Jan 2021 22:14:00 +0100 Subject: 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 --- docs/contributing/documentation.rst | 175 ---------------------------------- docs/contributing/index.rst | 13 +++ docs/contributing/issues-features.rst | 72 ++++++++++++++ docs/contributing/issues_features.rst | 72 -------------- 4 files changed, 85 insertions(+), 247 deletions(-) delete mode 100644 docs/contributing/documentation.rst create mode 100644 docs/contributing/index.rst create mode 100644 docs/contributing/issues-features.rst delete mode 100644 docs/contributing/issues_features.rst (limited to 'docs/contributing') 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//vyos-documentation.git (fetch) - origin https://github.com//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 new file mode 100644 index 00000000..02de2df6 --- /dev/null +++ b/docs/contributing/issues-features.rst @@ -0,0 +1,72 @@ +.. _issues_features: + +Issues and Feature requests +=========================== + +Bug Report / Issue +------------------ +Issues or bugs are found in any software project. VyOS is not an exception. + +All issues should be reported to the developers. This lets the developers know +what is not working properly. Without this sort of feedback every developer +will believe that everything is working correctly. + +I have found a bug, what should I do? +************************************* + +When you believe you have found a bug, it is always a good idea to verify the +issue prior to opening a bug request. + +* Consult the documentation_ to ensure that you have configured your system + correctly +* Get community support via Slack_ or our Forum_ + +Ensure the problem is reproducible +********************************** + +When you are able to verify that it is actually a bug, spend some time to +document how to reproduce the issue. This documentation can be invaluable. + +When you wish to have a developer fix a bug that you found, helping them +reproduce the issue is beneficial to everyone. Be sure to include information +about the hardware you are using, commands that you were running, any other +activities that you may have been doing at the time. This additional +information can be very useful. + +* What were you attempting to achieve? +* What was the configuration prior to the change? +* What commands did you use? Use e.g. ``run show configuration commands`` + +Include output +************** + +The output you get when you find a bug can provide lots of information. If you +get an error message on the screen, copy it exactly. Having the exact message +can provide detail that the developers can use. Like wise if you have any log +messages that also are from the time of the issue, include those. They may +also contain information that is helpful for the development team. + +Report a Bug +************ + +Create an account on VyOS Phabricator_. Phabricator_ is located at +https://phabricator.vyos.net. To create a bug-report use the quick link in the +left side under the specific project. + +* Provide as much information as you can +* Which version of VyOS are you using? ``run show version`` +* How can we reproduce this Bug? + +Feature Request +--------------- + +You have an idea of how to make VyOS better or you are in need of a specific +feature which all users of VyOS would benefit from? To send a feature request +please search Phabricator_ if there is already a request pending. You can +enhance it or if you don't find one, create a new one by use the quick link in +the left side under the specific project. + +.. _documentation: https://vyos.redthedocs.io +.. _Slack: https://slack.vyos.io +.. _Forum: https://forum.vyos.io +.. _Phabricator: https://phabricator.vyos.net \ No newline at end of file diff --git a/docs/contributing/issues_features.rst b/docs/contributing/issues_features.rst deleted file mode 100644 index 02de2df6..00000000 --- a/docs/contributing/issues_features.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _issues_features: - -Issues and Feature requests -=========================== - -Bug Report / Issue ------------------- -Issues or bugs are found in any software project. VyOS is not an exception. - -All issues should be reported to the developers. This lets the developers know -what is not working properly. Without this sort of feedback every developer -will believe that everything is working correctly. - -I have found a bug, what should I do? -************************************* - -When you believe you have found a bug, it is always a good idea to verify the -issue prior to opening a bug request. - -* Consult the documentation_ to ensure that you have configured your system - correctly -* Get community support via Slack_ or our Forum_ - -Ensure the problem is reproducible -********************************** - -When you are able to verify that it is actually a bug, spend some time to -document how to reproduce the issue. This documentation can be invaluable. - -When you wish to have a developer fix a bug that you found, helping them -reproduce the issue is beneficial to everyone. Be sure to include information -about the hardware you are using, commands that you were running, any other -activities that you may have been doing at the time. This additional -information can be very useful. - -* What were you attempting to achieve? -* What was the configuration prior to the change? -* What commands did you use? Use e.g. ``run show configuration commands`` - -Include output -************** - -The output you get when you find a bug can provide lots of information. If you -get an error message on the screen, copy it exactly. Having the exact message -can provide detail that the developers can use. Like wise if you have any log -messages that also are from the time of the issue, include those. They may -also contain information that is helpful for the development team. - -Report a Bug -************ - -Create an account on VyOS Phabricator_. Phabricator_ is located at -https://phabricator.vyos.net. To create a bug-report use the quick link in the -left side under the specific project. - -* Provide as much information as you can -* Which version of VyOS are you using? ``run show version`` -* How can we reproduce this Bug? - -Feature Request ---------------- - -You have an idea of how to make VyOS better or you are in need of a specific -feature which all users of VyOS would benefit from? To send a feature request -please search Phabricator_ if there is already a request pending. You can -enhance it or if you don't find one, create a new one by use the quick link in -the left side under the specific project. - -.. _documentation: https://vyos.redthedocs.io -.. _Slack: https://slack.vyos.io -.. _Forum: https://forum.vyos.io -.. _Phabricator: https://phabricator.vyos.net \ No newline at end of file -- cgit v1.2.3