Skip to content

opentelekomcloud-docs/sandbox

Repository files navigation

Sandbox

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.

Demo

demo

Initializing a repo

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

1. Log into GitHub with your credentials.

2. Open the project on GitHub in your browser, for example

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

3. Create a "Fork" of the repo

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.

image1

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

image2

4. Change content of the documents

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.

image3

5. Commit the changes

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.

image4

6. Create a Pull Request

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

image5

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.

image6

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.

image7

7. Review process

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.

image8

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

image9

8. Check rendered preview of the changes

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

image10

9. Check failed jobs

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.

10. Fixing issues

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

11. Peer review

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

12. Merge Pull request - publish changes

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.

13. Useful links

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

Releases

No releases published

Packages

No packages published

Languages