Structure of this repository:

• Books go into a top-level directory. For example: repo_dir/manage_quay/.

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

• A book’s TOC is defined in the master.adoc file contained within the book’s directory.

• master.adoc contains include statements to modules (chapters), which are created in the top-level modules/ directory.

• docinfo.xml in the book’s directory contains basic information about the book.

1. Get the Developer, the Maintainer, or the Owner permissions for the downstream repository. For that, contact a Maintainer or an Owner from this list. Default to contacting Vikram Goyal.

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

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

1. Create a new <branch-name> branch based off the 3.0-master branch and switch to it:

   $ git checkout -b <branch_name> 3.0-master

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

2. Edit the files and commit them using git add and git commit.

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

   $ git push origin <branch_name>

4. Create a pull request from <your_fork>/<branch_name> to quay/3.0-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 and 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.

5. Work together with the reviewer to finish your pull request, then ask them to merge it.

6. Shortly after your pull request is merged into the 3.0-master branch, your updates will become live in the Project Quay documentation.

Downstream documentation resides in the 3.0-stage branch of the downstream repository. However, Quay documentation is upstream-first. This means that all changes, including downstream-only content, first go to the 3.0-master branch of the upstream repository. After that, they are pushed to the 3.0-master branch of the downstream repository and get merged to the 3.0-stage branch.

In other words, to contribute to the downstream documentation:

1. Make your contribution in the upstream: How do I make a contribution?

2. Move it over to the downstream repository: How do I keep the downstream repository and branch up-to-date?

As other people push to the 3.0-master branch in the upstream repository, you need to keep your local 3.0-master up-to-date. It is optimal to do it regularly, for example, daily.

1. Switch to 3.0-master:

   $ git checkout 3.0-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 3.0-master:

   $ git rebase upstream/3.0-master

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

1. Bring your local 3.0-master up-to-date with the remote 3.0-master. How do I keep my local 3.0-master up-to-date with remote 3.0-master?

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

   $ git checkout <feature_branch>

3. Apply the commits from 3.0-master to <feature_branch>:

   $ git rebase upstream/3.0-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 3.0-master.

   $ git push --force origin <feature_branch>

To bring the downstream repository up-to-date with the upstream repository, you need to push the changes to the 3.0-master branch of the downstream repository and merge 3.0-master into 3.0-stage, from which downstream documentation is published:

1. Update your local 3.0-master branch. How do I keep my local 3.0-master up-to-date with remote 3.0-master?

2. Switch to the 3.0-master branch:

   $ git checkout 3.0-master

3. Push 3.0-master to the downstream repository:

   $ git push downstream

4. Switch to the 3.0-stage branch:

   $ git checkout 3.0-stage

5. Merge 3.0-master into 3.0-stage:

   $ git merge 3.0-master

6. Push 3.0-stage to the downstream repository:

   $ git push downstream

If you need to make a part of content appear only in the upstream documentation:

• Surround the content with these lines:

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

If you need to make a part of content appear only in the downstream documentation:

• Surround the content with these lines:

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