Uyuni Documentation Repository

Test Status

HTML

Syntax and Files

Weblate Translations

PDF Translations

Introduction

This is the source for the official Uyuni and SUSE Manager documentation. We welcome pull requests.

For more details on contributing to Uyuni documentation, visit the Uyuni Documentation Wiki. The wiki contains information about word usage, markup conventions, team processes, our docs toolchain, building locally, and publishing documentation. It also contains project planning information.

First Contribution

To contribute to Uyuni documentation:

Procedure: Contributing Using a Fork

1. Make sure you have a [github](github.com) account, and that you a`re signed in.

2. Navigate to the [Uyuni Documentation Repo](https://github.com/uyuni-project/uyuni-docs.git), click the Fork button in the top-right corner, and select the account you want to use.

3. Wait for github to create your fork and redirect you.

4. Clone the repository to your local machine. To find this URL, click the green Code button and copy the HTTPS URL:

   git clone https://github.com/<username>/uyuni-docs.git

5. Change into the directory that contains the repo, and check out the /master branch:

   cd uyuni-docs
   git checkout master

6. List the current remote branches:

   git remote -v

   This command should list two remotes, both marked origin, like this:

   origin  https://github.com/<username>/uyuni-docs.git (fetch)
   origin  https://github.com/<username>/uyuni-docs.git (push)

   The origin remotes are your own fork, and you can do whatever you want here without changing the upstream repository.

7. Add the uyuni-docs repo as an upstream:

   git remote add upstream https://github.com/uyuni-project/uyuni-docs.git

8. Check:

   git remote -v

   This command should now have the same two origin remotes as before, plus two more labelled upstream, like this:

   origin  https://github.com/<username>/uyuni-docs.git (fetch)
   origin  https://github.com/<username>/uyuni-docs.git (push)
   upstream  https://github.com/uyuni-project/uyuni-docs.git (fetch)
   upstream  https://github.com/uyuni-project/uyuni-docs.git (push)

9. Check out your fork’s master branch:

   git checkout master

10. Fetch the branches in the upstream repository:

    git fetch upstream

11. Merge the changes from the upstream master branch, into your fork’s master branch:

    git merge upstream/master

12. Create a new branch for the work you want to do. Make sure you give it an appropriate name, and include your username:

    git checkout -b update-readme-username

If you have write access to the repository, use this method instead:

Procedure: Contributing With Write Access

1. Clone the repository to your local machine:

   git clone https://github.com/uyuni-project/uyuni-docs.git

2. Change into the directory that contains the repo, and check out the /master branch:

   cd uyuni-docs
   git checkout master

3. Create a new working branch for your changes:

   git checkout -b branchname

Regardless of whether you use a fork or commit directly, when you have made your changes you can make a pull request (PR). Always check that your changes build locally first.

Procedure: Committing Changes and Creating a Pull Request

1. Make your changes and ensure your changes build locally. This step requires that you have your local environment set up correctly.

2. Add the updated files to your commit:

   git add .

3. Commit your changes:

   git commit -m "Commit message here"

4. Push your changes:

   git push

   If git prompts you to set an upstream in order to push, use this command:

   git push --set-upstream origin <branchname>

5. Create a pull request (PR) by navigating to https://github.com/uyuni-project/uyuni-docs and clicking Compare and Create Pull Request. Write an informative commit message detailing your changes, choose reviewers, and save your PR. If you haven’t yet finished the work you want to do, make sure you create a Draft PR by selecting it from the drop down box in the github web UI. This lets your reviewers know that you haven’t finished work yet, while still being transparent about what you are working on, and making sure we all understand current progress.

ℹ️	Choose your reviewers carefully! If you have made changes to the technical detail of the documentation, choose an appropriate subject matter expert (SME) to review those changes. Additionally, every change requires at least one documentation team member to approve.

Review Standards

These standards ensure that our documentation is accurate, that PRs are not left to age, and that the source code remains clean. Ensure you follow these standards if you are participating in the Uyuni documentation repository.

• If you are still working on a PR, add [WIP] to the title of your PR. This allows people to review the PR, but notifies reviewers that you have not completed work.

• Only the original author should merge PRs, do not merge other author’s PRs unless you have express permission from them to do so.

• Do not merge a PR until you have received the following approvals:

  • For a technical change, approval from at least one SME

  • For all changes, approval from at least one other member of the documentation team

Second Contribution

Once you have checked out the repo and want to keep working on things, you need to ensure that your local copy of the repo remains up to date. If you don’t do this, you will end up with merge conflicts.

Procedure: Second Contribution with a Fork

1. Check out your fork’s master branch:

   git checkout master

   You will get a message like this:

   Switched to branch 'master'
   Your branch is up to date with 'origin/master'.

   ❗	BEWARE! This is usually a lie!

2. Fetch the branches in the upstream repository:

   git fetch upstream

3. Merge the changes from the upstream master branch, into your fork’s master branch:

   git merge upstream/master

4. If you are continuing work you began earlier, check out the branch that contains your work. For new work, create a new branch.

Procedure: Second Contribution with Write Access

1. Check out the /master branch:

   git checkout master

   You will get a message like this:

   Switched to branch 'master'
   Your branch is up to date with 'origin/master'.

   ❗	BEWARE! This is usually a lie!

2. Fetch all current branches:

   git fetch --all

3. Update your local copy to match the remotes:

   git pull -ff

4. If you are continuing work you began earlier, check out the branch that contains your work. For new work, create a new branch.

Doing this regularly as you are working will mean you keep your local copies up to date and avoid conflicts. You should do it at least every day before you begin work, and again whenever you switch branches.

For example, you are working on two separate pieces of content, one in the feature_1 branch, and the other in the feature_2 branch:

1. Start your day by checking out master, fetching the branches, and updating your local copy:

   git checkout master
   git fetch upstream
   git merge upstream/master

   Or:

git checkout master
git fetch --all
git pull -ff

1. Begin work on the first piece of content by creating a new feature branch:

   git checkout -b feature_1

2. Make your changes for Feature 1, then commit them to your branch:

   git commit -m "Content for Feature 1"
   git push

3. Make a PR for Feature 1, by navigating to https://github.com/uyuni-project/uyuni-docs/ and clicking on Compare and Create Pull Request. Write an informative commit message detailing your changes, choose reviewers, and save your PR. If you haven’t yet finished the work you want to do on Feature 1, make sure you create a Draft PR by selecting it from the drop down box in the github web UI. That way, you can come back to Feature 1 later on.

4. Switch your local copy back to master, and update your local copy again:

   git checkout master
   git fetch upstream
   git merge upstream/master

   Or:

git checkout master
git fetch --all
git pull -ff

1. Now you can start work on Feature 2:

   git checkout -b feature_2

2. When you are finished on Feature 2, commit your changes and create another PR, just the same as you did for Feature 1.

⚠️	Never leave feature branches lying around on your local system. Create your PR as soon as possible, and make liberal use of the Draft feature. Commit to your feature branch early and often! Update your local copy from master whenever you switch branches.

Changelog Entries

Write your changes to the `.changlog` file. New entries are added to the top, in the following format. Each collection of release entries should be separated by dashed lines. These lines are used to extract the automated changelog notes for releases.

-----------------------------------------------------------------------

- Updated Foo chapter in Installation and Upgrade Guide for readability
- Documented Bar feature in Administration Guide
- Fixed error in Bat section of Upgrade Guide (bsc#1234567)

-----------------------------------------------------------------------

For guidelines: https://en.opensuse.org/openSUSE:Creating_a_changes_file_(RPM)

The Uyuni Documentation Team

• Joseph Cayouette @jcayouette

• Karl Eichwalder @keichwa

• Ornela Marić @0rnela