Contributing to Industrial Documentation¶

We believe that everyone has something valuable to contribute, whether you’re a coder, a writer, or a tester. Here’s how and why you can get involved:

Why join us? Work with like-minded people, develop your skills, connect with diverse professionals, and make a difference.
What do you get? Personal growth, recognition for your contributions, early access to new features and the joy of seeing your work appreciated.
Start early, start easy: Dive into code contributions, improve documentation, or be among the first testers. Your presence matters, regardless of experience or the size of your contribution.

The guidelines below will help keep your contributions effective and meaningful.

Code of conduct¶

When contributing, you must abide by the Ubuntu Code of Conduct.

License and copyright¶

Unless explicitly stated in the license headers of source files, all contributions to Industrial documentation are licensed under the Creative Commons Attribution-Share Alike (CC-BY-SA) 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

All contributors must sign the Canonical contributor license agreement, which grants Canonical permission to use the contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs).

Environment setup¶

Industrial documentation is built on top of Canonical’s Sphinx starter pack and hosted on Read the Docs. It is written in reStructuredText or MyST Markdown and built with Sphinx.

For general guidance, refer to the starter pack guide
For language and style conventions, refer to the Canonical style guides
In structuring, the documentation employs the Diátaxis approach

Fork and download the documentation repository¶

If you are working with this documentation set for the first time, you’ll need to create a fork of this repository on your GitHub account, and clone the forked repository.

Install dependencies¶

Go into the docs/ directory and run:

make install

This will create a virtual environment with all the tooling and packages required to validate and render the documentation.

Build and serve the docs¶

To get a live preview and validation of the documentation, run:

make run

This will provide a locally rendered version of the documentation at: {literalref}:http://localhost:8000

The rendered preview will get updated every time a document is modified and saved.

Validate the docs¶

Before you submit a PR, make sure to validate your changes with the following recipes:

make spelling  
make linkcheck  
make woke       # to check for non-inclusive language

For more information about the inclusive language check, see woke.

Propose changes¶

Submit your documentation changes via a pull request on GitHub.

Your changes will be reviewed in due time; if approved, they will eventually be merged.

Describing pull requests¶

To be properly considered, reviewed, and merged, your pull request must provide the following details:

Title: Summarize the change in a short, descriptive title.
Description: Explain the problem that your pull request solves. Mention any new features, bug fixes, or refactoring.
Relevant issues: Reference any related issues, pull requests, and repositories.

Commit structure and messages¶

Use separate commits for each logical change, and for changes to different sections in the Industrial documentation. Prefix your commit messages with the names of sections or pages that they affect, using the code tree structure. For example, start a commit that updates the reference page kernel boot parameters with ref/kernel-boot:.

Use conventional commits to ensure consistency across the project:

docs(ref/kernel-boot): Add example for nohz parameter

* Additional description goes here

Such structure makes it easier to review contributions and simplifies porting fixes to other branches.

Sign off on commits¶

To improve contribution tracking, we use the developer certificate of origin (DCO 1.1) and require a “sign-off” for any changes going into each branch.

The sign-off is a simple line at the end of the commit message certifying that you wrote it or have the right to commit it as an open-source contribution.

To sign off on a commit, use the --signoff or -s option in git commit. For example:

git commit -m "docs(ref/kernel-boot): Add example for nohz parameter" -s