Modifying content on this site

You have two options for editing content: directly in your browser using GitHub, or using a Git-based workflow from your local work environment.

Notes on content additions

Sections: Generally, content additions should fit somewhere within the existing top-level and second-level sections. Try not to introduce a new top-level or second-level section.

Screenshots: If you are contributing a change that contains screenshots from Cleura Cloud Management Panel, they should use a resolution of 1920×1080 pixels (1080p). If your screen uses a larger resolution, use Firefox Responsive Design Mode or Chrome/Chromium Device Mode to configure your browser with 1080p. Screenshots should be added to a directory named assets, located in the same directory as the Markdown file you are adding or editing.

CLI screen dumps: If you are contributing a change that contains a screen dump from the openstack command-line client, please limit its width to 100 characters. You can do this by setting the following environment variable in your terminal, before you start work on your change.

export CLIFF_MAX_TERM_WIDTH=100

Modifying content from your browser

Every page on this site has an Edit button (). If you click it, it’ll take you straight to its corresponding source page in GitHub. Then, you can follow GitHub’s documentation on how to propose changes to another user’s repository.

Modifying content using Git

The Git repository for this site lives on GitHub. You can fork that repository, make the proposed changes in your fork, and then send us a standard GitHub pull request.

For this purpose, use git in combination with either GitHub’s web interface, or the gh command-line interface (CLI).

First, create a fork of the documentation repository:

git clone git@github.com:<yourusername>/<your-repo-fork> cleura cloud-docs
cd cleura cloud-docs

gh repo fork --clone https://github.com/citynetwork/docs -- cleura cloud-docs
cd cleura cloud-docs

Next, create a local topic branch and make your modifications:

git checkout -b <your-topic-branch-name>
# edit your files
git add <files-to-add>
git commit

Please see our notes on commit messages.

Finally, create a pull request (PR) from your changes:

git push origin <your-topic-branch-name>

gh pr create --fill

Monitoring changes as you edit

To see your changes as you work on them, you can use tox. Having created a topic branch with your modifications, run:

cd cleura cloud-docs
git checkout <your-topic-branch-name>
tox -e serve

A local copy of the documentation will then run on your local machine and be accessible from http://localhost:8000 in your browser.

When you are planning to make several changes in rapid succession, you may want to speed up rendering the site after each change. You may do so by disabling a plugin that checks all links (including external links) for accessibility:

cd cleura cloud-docs
export DOCS_ENABLE_HTMLPROOFER=false
tox -e serve

Commit messages

When you submit a change, you will need to provide a commit message, which is very nearly as important as the change itself. Excellent guides on what constitutes a good commit message are available from Tim Pope and Colleen Murphy.

In addition, we have adopted the Conventional Commits style for commit message subjects. Please make sure that your commit message starts with one of the following prefixes:

• feat: denotes a content addition, such as adding documentation for some Cleura Cloud functionality that was not included in the documentation before.
• fix: denotes a content correction, such as fixing a documentation bug.
• build: denotes a change to the build process, such as an improvement to a CI check.
• chore: denotes a minor change that is neither a feature, nor a fix, nor a build improvement, such as when you edit the .mailmap file.
• docs: denotes a change to the documention for this site, such as an update to the README.md file.