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.adocfile contained within the book’s directory. -
master.adoccontainsincludestatements to modules (chapters), which are created in the top-levelmodules/directory. -
docinfo.xmlin the book’s directory contains basic information about the book.
-
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.
-
Fork the upstream repository by clicking "Fork".
-
Clone your fork of the repository to your computer:
$ git clone git@github.com:<USERNAME>/quay-docs.git
Substitute <USERNAME> with your GitHub user name.
-
Navigate to the cloned repository:
$ cd quay-docs
-
Add the
upstreamremote:$ git remote add upstream git@github.com:quay/quay-docs.git
-
Add the
downstreamremote:$ git remote add downstream git@gitlab.cee.redhat.com:red-hat-quay-documentation/quay-documentation.git
-
Create a new <branch-name> branch based off the
3.0-masterbranch 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.
-
Edit the files and commit them using
git addandgit commit. -
Push your commits to your fork of the upstream repository:
$ git push origin <branch_name>
-
Create a pull request from
<your_fork>/<branch_name>toquay/3.0-master. For that, either:-
visit the link from the output of the previous step (the link is there after the first push only)
-
navigate to https://github.com/<YOUR_USERNAME>/quay-docs and use the interface to create the pull request
As you cr 8919 eate the pull request, tag one of the repository collaborators and ask them to review the pull request.
-
-
Work together with the reviewer to finish your pull request, then ask them to merge it.
-
Shortly after your pull request is merged into the
3.0-masterbranch, 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:
-
Make your contribution in the upstream: How do I make a contribution?
-
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.
-
Switch to
3.0-master:$ git checkout 3.0-master
-
Fetch the commits that are in the upstream repository but not in your local repository:
$ git fetch upstream
-
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:
-
Bring your local
3.0-masterup-to-date with the remote3.0-master. How do I keep my local3.0-masterup-to-date with remote3.0-master? -
Switch to the feature branch that you want to update:
$ git checkout <feature_branch>
-
Apply the commits from
3.0-masterto <feature_branch>:$ git rebase upstream/3.0-master
-
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
--forceoption:ImportantNever use the
--forceargument when pushing to3.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:
-
Update your local
3.0-masterbranch. How do I keep my local3.0-masterup-to-date with remote3.0-master? -
Switch to the
3.0-masterbranch:$ git checkout 3.0-master
-
Push
3.0-masterto the downstream repository:$ git push downstream
-
Switch to the
3.0-stagebranch:$ git checkout 3.0-stage
-
Merge
3.0-masterinto3.0-stage:$ git merge 3.0-master
-
Push
3.0-stageto 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[]