Uyuni Documentation Repository
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:
-
Make sure you have a [github](github.com) account, and that you’re signed in.
-
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. -
Wait for github to create your fork and redirect you.
-
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
-
Change into the directory that contains the repo, and check out the
/master
branch:cd uyuni-docs git checkout master
-
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. -
Add the uyuni-docs repo as an upstream:
git remote add upstream https://github.com/uyuni-project/uyuni-docs.git
-
Check:
git remote -v
This command should now have the same two
origin
remotes as before, plus two more labelledupstream
, 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)
-
Check out your fork’s
master
branch:git checkout master
-
Fetch the branches in the upstream repository:
git fetch upstream
-
Merge the changes from the upstream
master
branch, into your fork’smaster
branch:git merge upstream/master
-
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:
-
Clone the repository to your local machine:
git clone https://github.com/uyuni-project/uyuni-docs.git
-
Change into the directory that contains the repo, and check out the
/master
branch:cd uyuni-docs git checkout master
-
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.
-
Make your changes and ensure your changes build locally. This step requires that you have your local environment set up correctly.
-
Add the updated files to your commit:
git add .
-
Commit your changes:
git commit -m "Commit message here"
-
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>
-
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. |
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.
-
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!
-
Fetch the branches in the upstream repository:
git fetch upstream
-
Merge the changes from the upstream
master
branch, into your fork’smaster
branch:git merge upstream/master
-
If you are continuing work you began earlier, check out the branch that contains your work. For new work, create a new branch.
-
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!
-
Fetch all current branches:
git fetch --all
-
Update your local copy to match the remotes:
git pull -ff
-
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:
-
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
-
Begin work on the first piece of content by creating a new feature branch:
git checkout -b feature_1
-
Make your changes for Feature 1, then commit them to your branch:
git commit -m "Content for Feature 1" git push
-
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. -
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
-
Now you can start work on Feature 2:
git checkout -b feature_2
-
When you’re 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. |
The Uyuni Documentation Team
-
Joseph Cayouette @jcayouette
-
Karl Eichwalder @keichwa
-
Lana Brindley @Loquacity