How to contribute

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.

Releases and versions

The 12-factor project uses semantic versioning; major releases occur once or twice a year.

The release notes can be found here.

Environment setup

Submissions

If you want to address an issue or a bug in the 12-factor project, notify in advance the people involved to avoid confusion; also, reference the issue or bug number when you submit the changes.

  • Fork our GitHub repository and add the changes to your fork, properly structuring your commits, providing detailed commit messages and signing your commits.

  • Make sure the updated project builds and runs without warnings or errors; this includes linting, documentation, code and tests.

  • Submit the changes as a pull request (PR).

Your changes will be reviewed in due time; if approved, they will be eventually 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.

  • Testing: Explain whether new or updated tests are included.

  • Reversibility: If you propose decisions that may be costly to reverse, list the reasons and suggest steps to reverse the changes if necessary.

Commit structure and messages

Use separate commits for each logical change, and for changes to different components.

Use conventional commits to ensure consistency across the project:

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

Signing 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 option in git commit.

Code

Formatting and linting

Structure

  • Check linked code elements: Check that coupled code elements, files and directories are adjacent. For instance, store test data close to the corresponding test code.

  • Group variable declaration and initialization: Declare and initialize variables together to improve code organization and readability.

  • Split large expressions: Break down large expressions into smaller self-explanatory parts. Use multiple variables where appropriate to make the code more understandable and choose names that reflect their purpose.

  • Use blank lines for logical separation: Insert a blank line between two logically separate sections of code. This improves its structure and makes it easier to understand.

  • Avoid nested conditions: Avoid nesting conditions to improve readability and maintainability.

  • Remove dead code and redundant comments: Drop unused or obsolete code and comments. This promotes a cleaner code base and reduces confusion.

  • Normalize symmetries: Treat identical operations consistently, using a uniform approach. This also improves consistency and readability.

Best practices

Tests

All code contributions must include tests.

To run the tests locally before submitting your changes:

TODO: test command 1
TODO: test command 2

Documentation

The documentation is stored in the docs directory of the repository. It is based on the Canonical starter pack and hosted on Read the Docs.

For syntax help and guidelines, refer to the Canonical style guides.

In structuring, the documentation employs the Diátaxis approach.

To run the documentation locally before submitting your changes:

make run

Automatic checks

GitHub runs automatic checks on the documentation to verify spelling, validate links and suggest inclusive language.

You can (and should) run the same checks locally:

make spelling
make linkcheck
make woke