SUSE Manager Documentation Repository

Introduction

This is the source for the official SUSE Manager documentation.

We welcome pull requests. Please follow these instructions to create your pull request.

For more details on contributing to SUSE Manager documentation, visit the SUSE Manager Documentation Wiki. The wiki contains information about word usage, markup conventions, our docs toolchain, building locally, and publishing documentation.

First Contribution

To contribute to SUSE Manager documentation:

1. Clone the repository to your local machine:

   git clone https://github.com/SUSE/doc-susemanager.git

2. Check out the /master branch:

   git checkout master

3. Create a new working branch for your changes:

   git checkout -b branchname

4. Navigate to the adoc directory and make your changes using your preferred text editor.

5. Ensure your changes build locally. This step requires that you have your local environment set up correctly. <!-- TODO: add environment setup instructions -→

6. Add the updated files to your commit:

   git add .

7. Commit your changes:

   git commit -m "Commit message here"

8. 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>

9. Create a pull request (PR) by navigating to https://github.com/SUSE/doc-susemanager 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, 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 SUSE Manager 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.

Every day, before you begin work, update your copy of master:

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

Now you can go ahead and check out the branch you are working on.

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 --all
   git pull -ff

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

   git checkout -b feature_1

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

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

4. Make a PR for Feature 1, by navigating to https://github.com/SUSE/doc-susemanager 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.

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

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

6. Now you can start work on Feature 2:

   git checkout -b feature_2

7. 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 SUSE Manager Documentation Team

• Joseph Cayouette @jcayouette

• Karl Eichwalder @keichwa

• Lana Brindley @Loquacity