kelvin/warewulf
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Reflow all userdocs text

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.co>
This commit is contained in:
Jonathon Anderson
2023-02-22 00:02:08 -07:00
parent 3d7438bc6c
commit ef31b3ddb8
24 changed files with 1005 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
userdocs/contributing/contributing.rst
View File

@@ -2,35 +2,57 @@
Contributing
============
Warewulf is an open source project, meaning we have the challenge of limited resources. We are grateful for any support that you can offer. Helping other users, raising issues, helping write documentation, or contributing code are all ways to help!
Warewulf is an open source project, meaning we have the challenge of
limited resources. We are grateful for any support that you can
offer. Helping other users, raising issues, helping write
documentation, or contributing code are all ways to help!
Join the community
==================
This is a huge endeavor, and your help would be greatly appreciated! Post to online communities about Warewulf, and request that your distribution vendor, service provider, and system administrators include Warewulf for you!
This is a huge endeavor, and your help would be greatly appreciated!
Post to online communities about Warewulf, and request that your
distribution vendor, service provider, and system administrators
include Warewulf for you!
Warewulf on Slack
-----------------
Many of our users come to Slack for quick help with an issue. You can find us at `HPCng <https://join.slack.com/t/hpcng/shared_invite/zt-k9atb2dj-rnlPjSh5Os3Ks6vlDEOyAA>`_.
Many of our users come to Slack for quick help with an issue. You can
find us at `HPCng
<https://join.slack.com/t/hpcng/shared_invite/zt-k9atb2dj-rnlPjSh5Os3Ks6vlDEOyAA>`_.
Raise an Issue
==============
For general bugs/issues, you can open an issue `at the GitHub repo <https://github.com/hpcng/warewulf/issues/new>`_. However, if you find a security related issue/problem, please email HPCng directly at `security@hpcng.org <mailto:security@hpcng.org>`_. More information about the HPCng security policies and procedures can be found `here <https://hpcng.org/security-policy>`_.
For general bugs/issues, you can open an issue `at the GitHub repo
<https://github.com/hpcng/warewulf/issues/new>`_. However, if you find
a security related issue/problem, please email HPCng directly at
`security@hpcng.org <mailto:security@hpcng.org>`_. More information
about the HPCng security policies and procedures can be found `here
<https://hpcng.org/security-policy>`_.
Contribute to the code
======================
We use the traditional `GitHub Flow <https://guides.github.com/introduction/flow>`_ to develop. This means that you fork the main repo, create a new branch to make changes, and submit a pull request (PR) to the master branch.
We use the traditional `GitHub Flow
<https://guides.github.com/introduction/flow>`_ to develop. This means
that you fork the main repo, create a new branch to make changes, and
submit a pull request (PR) to the master branch.
Check out our official `CONTRIBUTING.md <https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md>`_ document, which also includes a `code of conduct <https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md#code-of-conduct>`_.
Check out our official `CONTRIBUTING.md
<https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md>`_
document, which also includes a `code of conduct
<https://github.com/hpcng/warewulf/blob/master/CONTRIBUTING.md#code-of-conduct>`_.
Step 1. Fork the repo
---------------------
To contribute to Warewulf, you should obtain a GitHub account and fork the `Warewulf <https://github.com/hpcng/warewulf>`_ repository. Once forked, clone your fork of the repo to your computer. (Obviously, you should replace ``your-username`` with your GitHub username.)
To contribute to Warewulf, you should obtain a GitHub account and fork
the `Warewulf <https://github.com/hpcng/warewulf>`_ repository. Once
forked, clone your fork of the repo to your computer. (Obviously, you
should replace ``your-username`` with your GitHub username.)
.. code-block:: bash
@@ -40,10 +62,11 @@ To contribute to Warewulf, you should obtain a GitHub account and fork the `Ware
Step 2. Checkout a new branch
-----------------------------
`Branches <https://guides.github.com/introduction/flow>`_` are a way of
isolating your features from the main branch. Given that we’ve just cloned the
repo, we will probably want to make a new branch from master in which to work on
our new feature. Lets call that branch ``new-feature``:
`Branches <https://guides.github.com/introduction/flow>`_ are a way
of isolating your features from the main branch. Given that we’ve just
cloned the repo, we will probably want to make a new branch from
master in which to work on our new feature. Lets call that branch
``new-feature``:
.. code-block:: bash
@@ -51,37 +74,50 @@ our new feature. Lets call that branch ``new-feature``:
git checkout -b new-feature
.. note::
You can always check which branch you are in by running ``git branch``.
You can always check which branch you are in by running ``git
branch``.
Step 3. Make your changes
-------------------------
On your new branch, go nuts! Make changes, test them, and when you are happy commit the changes to the branch:
On your new branch, go nuts! Make changes, test them, and when you are
happy commit the changes to the branch:
.. code-block:: bash
git add file-changed1 file-changed2...
git commit -m "what changed?"
This commit message is important - it should describe exactly the changes that you have made. Good commit messages read like so:
This commit message is important - it should describe exactly the
changes that you have made. Good commit messages read like so:
.. code-block:: bash
git commit -m "changed function getConfig in functions.go to output csv to fix #2"
git commit -m "updated docs about shell to close #10"
The tags ``close #10`` and ``fix #2`` are referencing issues that are posted on the upstream repo where you will direct your pull request. When your PR is merged into the master branch, these messages will automatically close the issues, and further, they will link your commits directly to the issues they intend to fix. This will help future maintainers understand your contribution, or (hopefully not) revert the code back to a previous version if necessary.
The tags ``close #10`` and ``fix #2`` are referencing issues that are
posted on the upstream repo where you will direct your pull
request. When your PR is merged into the master branch, these messages
will automatically close the issues, and further, they will link your
commits directly to the issues they intend to fix. This will help
future maintainers understand your contribution, or (hopefully not)
revert the code back to a previous version if necessary.
Step 4. Push your branch to your fork
-------------------------------------
When you are done with your commits, you should push your branch to your fork (and you can also continuously push commits here as you work):
When you are done with your commits, you should push your branch to
your fork (and you can also continuously push commits here as you
work):
.. code-block:: bash
git push origin new-feature
Note that you should always check the status of your branches to see what has been pushed (or not):
Note that you should always check the status of your branches to see
what has been pushed (or not):
.. code-block:: bash
@@ -90,12 +126,24 @@ Note that you should always check the status of your branches to see what has be
Step 5. Submit a Pull Request
-----------------------------
Once you have pushed your branch, then you can go to your fork (in the web GUI on GitHub) and `submit a Pull Request <https://help.github.com/articles/creating-a-pull-request>`_. Regardless of the name of your branch, your PR should be submitted to the ``main`` branch. Submitting your PR will open a conversation thread for the maintainers of Warewulf to discuss your contribution. At this time, the continuous integration that is linked with the code base will also be executed. If there is an issue, or if the maintainers suggest changes, you can continue to push commits to your branch and they will update the Pull Request.
Once you have pushed your branch, then you can go to your fork (in the
web GUI on GitHub) and `submit a Pull Request
<https://help.github.com/articles/creating-a-pull-request>`_. Regardless
of the name of your branch, your PR should be submitted to the
``main`` branch. Submitting your PR will open a conversation thread
for the maintainers of Warewulf to discuss your contribution. At this
time, the continuous integration that is linked with the code base
will also be executed. If there is an issue, or if the maintainers
suggest changes, you can continue to push commits to your branch and
they will update the Pull Request.
Step 6. Keep your branch in sync
--------------------------------
Cloning the repo will create an exact copy of the Warewulf repository at that moment. As you work, your branch may become out of date as others merge changesinto the upstream master. In the event that you need to update a branch, you will need to follow the next steps:
Cloning the repo will create an exact copy of the Warewulf repository
at that moment. As you work, your branch may become out of date as
others merge changesinto the upstream master. In the event that you
need to update a branch, you will need to follow the next steps:
.. code-block:: bash
@@ -107,4 +155,4 @@ Cloning the repo will create an exact copy of the Warewulf repository at that mo
# to update your fork
git push origin master
git checkout new-feature
git merge master
git merge master

24
userdocs/contributing/development-environment-vbox.rst
View File

@@ -1,11 +1,12 @@
====================================
Development Environment (VirtualBox)
====================================
I have VirtualBox running on my desktop.
1. Create a NAT Network (a private vlan) to be used for the Warewlf Server and compute nodes inside the VirtualBox. Make sure to turnoff DHCP service within this NAT Network.
1. Create a NAT Network (a private vlan) to be used for the Warewlf
Server and compute nodes inside the VirtualBox. Make sure to
turnoff DHCP service within this NAT Network.
.. code-block:: console
@@ -13,7 +14,12 @@ I have VirtualBox running on my desktop.
VBoxManage natnetwork add --netname wwnatnetwork --network "10.0.8.0/24" --enable --dhcp off
2. Create a Centos 7 development Virtual machine (wwdev) to be used as the Warewulf Server. Enable two Network adapters one with a standard NAT and SSH port mapping such that you can access this VM from the host machine. Assign the second network adapter to the NAT Network created in step #1. Assign sufficient memory (e.g: 4GB) to the VM.
2. Create a Centos 7 development Virtual machine (wwdev) to be used as
the Warewulf Server. Enable two Network adapters one with a
standard NAT and SSH port mapping such that you can access this VM
from the host machine. Assign the second network adapter to the NAT
Network created in step #1. Assign sufficient memory (e.g: 4GB) to
the VM.
.. code-block:: console
@@ -135,7 +141,14 @@ I have VirtualBox running on my desktop.
sudo wwctl server start
sudo wwctl server status
4. Create a new guest VM instance inside the VirtualBox to be the Warewulf client/compute node. Under the system configuration make sure to select the optical and network options only for the boot order. The default iPXE used by VirtualBox does not come with bzImage capability which is needed for Warewulf. Download the ipxe.iso available at ipxe.org and mount the ipxe.iso to the optical drive. Enable one Network adapter for this VM and assign it to the NAT Network created in step #1 above.
4. Create a new guest VM instance inside the VirtualBox to be the
Warewulf client/compute node. Under the system configuration make
sure to select the optical and network options only for the boot
order. The default iPXE used by VirtualBox does not come with
bzImage capability which is needed for Warewulf. Download the
ipxe.iso available at ipxe.org and mount the ipxe.iso to the
optical drive. Enable one Network adapter for this VM and assign it
to the NAT Network created in step #1 above.
.. code-block:: console
@@ -144,4 +157,5 @@ I have VirtualBox running on my desktop.
# VM Settings -> Storage and mount the above download ipxe.so to the Optical Drive.
# VM Settings -> Network Enable adapter #1, attach to 'Nat Network' and choose 'wwnatnetwork' from the drop down list.
Boot your node and watch the console and the output of the Warewulfd process
Boot your node and watch the console and the output of the Warewulfd
process.

19
userdocs/contributing/documentation.rst
View File

@@ -2,10 +2,21 @@
Documentation
=============
We (like almost all open source software providers) have a documentation dilemma… We tend to focus on the code features and functionality before working on documentation. And there is very good reason for this: we want to share the love so nobody feels left out!
We (like almost all open source software providers) have a
documentation dilemma… We tend to focus on the code features and
functionality before working on documentation. And there is very good
reason for this: we want to share the love so nobody feels left out!
You can contribute to the documentation by `raising an issue to suggest an improvement <https://github.com/hpcng/warewulf-web/issues/new>`_ or by sending a `pull request <https://github.com/hpcng/warewulf-web/compare>`_ on `our repository <https://github.com/hpcng/warewulf-web>`_.
You can contribute to the documentation by `raising an issue to
suggest an improvement
<https://github.com/hpcng/warewulf-web/issues/new>`_ or by sending a
`pull request <https://github.com/hpcng/warewulf-web/compare>`_ on
`our repository <https://github.com/hpcng/warewulf-web>`_.
The current documentation is generated with `Docusaurus <https://v2.docusaurus.io/docs/>`_.
The current documentation is generated with `Docusaurus
<https://v2.docusaurus.io/docs/>`_.
For more information on using Git and GitHub to create a pull request suggesting additions and edits to the docs, see the `section on contributing to the code <contributing>`_. The procedure is identical for contributions to the documentation and the code base.
For more information on using Git and GitHub to create a pull request
suggesting additions and edits to the docs, see the `section on
contributing to the code <contributing>`_. The procedure is identical
for contributions to the documentation and the code base.