This is a sandbox project The aim of this project is to provide easy and understandable explanation how to work with GitOps documentation. How to contribute, review, propose changes, suggest fixes and validate previews.

These steps are necessary to initialize a project repo enabling you to contribute to the documentation of that project:

https://github.com/opentelekomcloud-docs/sandbox

Click on "Fork" on the top-right of the page. If you have several identities configured, select the one you want to use for contributing to the documentation.

After succesful fork you should see a forked project under your private identity.

Edit the files with an "rst" extension to reflect your additions or changes to the documentation. The root node of the documentation is in "index.rst". Make sure that all restructured text files are linked from this root node, since Sphinx will complain otherwise.

Commit the changes either to the main branch of your forked project or in case of potential multiple independent changes you can push it to separate branch.

Once you succesfully pushed all your changes to your forked project you are ready to create a pull request to the upstream project

During creation of pull request you can quickly review your changes which will be included in PR and if there are no conflicts you see "Able to merge" green message.

In next step you can assign reviewer to your changes, you can describe what has been changed in PR description and proceed with PR. In case you are not fully ready with all your changes but you would like to see rendered web result you can create draft pull request.

The review phase starts. Now two things happen in parallel: The automated and the manual review. Let's first look into the automated checks: Under "Checks" tab of pull request you can find the progress of the automated review jobs. Zuul is instantly simulating to merge your changes and build the whole project. If build succeeded you can navigate to respective "build" link and observe created artifacts.

For your connvience Zuul is pre-rending html documentation incorporating your changes under "Docs preview site" link.

Navigate to the modified content of the rendered documentation to validate whether your changes are correct.

If, however, Zuul and Sphinx are not able to build the project successfully, several red stop signs appear. To investigate for the cause, identify the symbol for " checks have failed" and click on "Details" right next to it. In the main section of the new screen is a headline "Summary". Under that there's probably a red cross stating "FAILURE", the time Zuul needed to perform the checks, and a link. Click on it.

You now see a job detail page generated by Zuul. There's lots of information about the job and Zuul's configuration, but we are interested only in the 'Logs' tab on the lower part of the screen. In the tab there's a long file 'job-output.txt', that details all steps the Zuul performed to verify your changes: It creates some compute resources, installs all necessary software, checks out the repository including your changes, and starts the build process. You should watch out for a message 'Running Sphinx vX.Y.Z'. A few lines later there's usually the error listed, just before the next 'ERROR' line. Depending on the type of the error, the important information might be in another line, though.

Once you found the cause of the failed check, return to your local repository, and fix it.

In the meantime, the manual review phase has started. TODO Add screenshot how to request changes by reviewer.

If the project agrees that the change set is ready to be merged, someone has to put the label "gate" to the commit. To do so, open the PR, select the "Conversation" tab, and locate the "Labels" section on the right-hand sidebar. Click on the tiny wheel and select the "gate" label.

How to rebase your forked repo

How to install Github CLI tools

How to create fork with Github CLI tools

Online RST editor

RST tutorial