Contributing to Red Hat Quay documentation

Repository structure

The Red Hat Quay repository is structured as follows:

• Books go into a top-level directory. For example, repo_dir/manage_quay or repo_dir/release_notes.

• Each book directory has a symlink to the top-level repo_dir/modules directory.

• A book’s table of contents, or ToC, is defined in the master.adoc that is contained within the book’s directory. Each directory has its own master.adoc file.

• The master.adoc file contains include statements to modules, which act as chapters and subchapters. These are created in the top-level modules/ directory.

• The docinfo.xml in the book’s directory contains basic information about the book, such as the product name, the product version, and the organization name.

Setting up your repository for contribution

1. For downstream contribution, which is the official Red Hat Quay documentation found on the Red Hat portal, you must obtain Developer, Maintainer, or Owner permissions for the downstream repository.

   To obtain the necessary permissions, contact a Maintainer or Owner from the Gitlab project members list. Default to contacting Steven Smith.

2. Fork the upstream repository by clicking the Fork button.

3. Clone your fork of the repository to your computer:

   $ git clone [email protected]:<username>/quay-docs.git

   Substitute <username> with your GitHub user name.

4. Navigate to the cloned repository:

   $ cd quay-docs

5. Add the upstream remote:

   $ git remote add upstream [email protected]:quay/quay-docs.git

6. Add the downstream remote:

   $ git remote add downstream [email protected]:red-hat-quay-documentation/quay-documentation.git

How do I make a contribution?

To contribute to Red Hat Quay documentation, you must create a new feature branch based off of the master branch.

1. Checkout the master branch if you have not already:

   $ git checkout master

2. Create a new feature branch based off the master branch:

   $ git checkout -b <branch_name> master

   Substitute <branch_name> with a name that reflects the contribution you intend to make.

3. Edit the files and commit them using git add and git commit. Make your commit in present tense, highlighting the change that you have made.

4. Push your commits to your fork of the upstream repository:

   $ git push origin <branch_name>

5. Create a pull request from <your_fork>/<branch_name> to quay/master. For that, either:

   1. Visit the link from the output of the previous step. The link is there after the first push only.

   2. Navigate to https://github.com/<your_username>/quay-docs. Use the interface to create the pull request

   As you create the pull request, tag one of the repository collaborators and ask them to review the pull request. The default contact should be Steven Smith.

6. Work with the reviewer to finish your pull request. After the suggested changes have been made, the reviewer will merge the pull request.

7. After your pull request is merged into the master branch, your updates will become live in the Project Quay documentation. Eventually, those changes will end up on the portal.

How do I make a contribution to the downstream documentation?

Like upstream documentation, downstream documentation primarily resides in the master branch of the downstream repository. For most users, the only necessary step is to create a feature branch from the master branch.

To make a contribution to upstream documentation, follow the instructions at How do I make a contribution?. Be sure to work with the documentation lead for Red Hat Quay to get the content reviewed, merged, and published on the downstream portal.

How Red Hat Quay downstream documentation is branched

After you have created and merged a pull request, relevant branches are then reset to match the master branch. For example, if the current version of Red Hat Quay is 3.10, then the relevant 3.10 branch (redhat-3.10) is reset to match the master. branch. This ensures that the most recent content changes are up to date in the most recent version branch.

After the the most recent branch is reset to match the master branch, the 3.0-stage branch is then reset to match the most recent version branch (for example, 3.0-stage is reset to match redhat-3.10). The reason for this is that the Red Hat Quay 3 version is copied directly from the most recent version of Red Hat Quay.

How do I keep my local master up-to-date with remote master?

As contributors push and merge pull requests to the master branch, you must keep your local master branch up to date. Prior to making any changes to the documentation, you should rebase your local master branch to match the most recent version of the remote master branch.

1. Check out the master branch:

   $ git checkout master

2. Fetch the commits that are in the upstream repository but not in your local repository:

   $ git fetch upstream

3. Apply the fetched commits to your local master:

   $ git rebase upstream/master

Now, your local master branch is up to date.

How do I keep my feature branch up-to-date with the master branch?

As new commits appear on the master branch, your existing feature branch does not automatically incorporate those commits. To prevent your feature branch and master from diverging, you need to manually update your feature branch to the master branch:

1. Bring your local master brnach up-to-date with the remote master branch by following the instructions at How do I keep my local master up-to-date with remote master?.

2. Switch to the feature branch that you want to update:

   $ git checkout <feature_branch>

3. Apply the commits from the master branch to your <feature_branch>:

   $ git rebase upstream/master

4. Push the updated <feature_branch> to your fork of the upstream repository. Since your local <feature_branch> has been updated, it might be incompatible with the remote <feature_branch>, so you need to use the --force option:

   Important

   Never use the --force argument when pushing to master.

   $ git push --force origin <feature_branch>

How do I make content appear in upstream but not in downstream?

You can make content appear only in the upstream by using the ifdef::upstream conditional around the content that you only want to appear upstream. For example:

ifdef::upstream[]
<Content that should be in upstream only.>
endif::upstream[]

How do I make content appear in downstream but not in upstream?

You can make content appear only in the downstream by using the ifdef::downstream conditional around the content that you only want to appear downstream. For example:

ifdef::downstream[]
<Content that should be in downstream only.>
endif::downstream[]