Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
360 lines (259 loc) · 12 KB

CONTRIBUTING.md

File metadata and controls

360 lines (259 loc) · 12 KB
Raw

Contributing to Sphinx Stack development

The Sphinx Stack is a shared foundation for Sphinx documentation projects, and contributions help improve the documentation of all its users. The Documentation Practice team performs most of the work, but all contributors are welcome.

Common contributions include:

  • Bug fixes: Build errors, broken links, configuration issues
  • Improvements: Better defaults, new extensions, workflow enhancements, new or improved style rules
  • Dependency updates: Security patches, compatibility fixes, better tooling

If you run into any problems or see room for improvement, we encourage you to open an issue or even contribute a fix.

This guide only covers contributions to development. If you're interested in contributing to the Sphinx Stack documentation, refer to the documentation repository's guide.

Review the project expectations

Review these three documents before contributing:

Ubuntu Code of Conduct

When contributing, you must abide by the Ubuntu Code of Conduct. Projects governed by Canonical expect good conduct and excellence from every member.

Canonical Contributor License Agreement

Code contributions can only be accepted from contributors who have signed our Contributor License Agreement (CLA). Signing the agreement grants Canonical permission to use your contributions, and you remain the copyright owner of your work (no copyright assignment occurs).

Review the terms of the agreement before signing it or committing anything. If you agree and choose to sign it, your work can be incorporated into the repository.

Open source license

The Sphinx Stack is licensed under GPL-3.0.

Report an issue or open a request

If you find a bug or feature gap in the Sphinx Stack, look for it in the project's GitHub issues first. Add your voice to the thread if you have fresh input.

If the bug or feature doesn't have an issue, open one.

What belongs in the Sphinx Stack

The Sphinx Stack is designed to be a minimal, flexible foundation for diverse documentation projects.

Belongs in the Sphinx Stack:

  • Bug fixes for core functionality
  • Improvements to default configuration that benefit all users
  • Dependency updates for security or compatibility

May not belong in the Sphinx Stack:

  • Optional tooling or features (these should be opt-in and implemented by projects using the Sphinx Stack)
  • Opinionated formatting or linting rules that would cause a sizable portion of existing doc sets to fail checks suddenly
  • Changes that conflict with existing workflows
  • Features that are project-specific rather than general-purpose
  • UI-related changes may be better suited for the ongoing alternative theme update project (ask maintainers)

When in doubt, open an issue first to discuss whether the change aligns with the project's goals.

Development setup

Create a personal fork of the repository, then clone it and add the upstream remote:

With SSH:

git clone git@github.com:<username>/sphinx-stack
cd sphinx-stack
git remote add upstream git@github.com:canonical/sphinx-stack
git fetch upstream

With HTTPS:

git clone https://github.com/<username>/sphinx-stack
cd sphinx-stack
git remote add upstream https://github.com/canonical/sphinx-stack
git fetch upstream

Install dependencies and verify the build:

cd docs
make install
make html

Contribute a change

Research the topic

All significant work should be tied to an existing issue. Before starting, comment on the issue to have it assigned to you.

Minor changes

Check GitHub issues for existing reports. If none exist, open one and state your interest in working on it.

Major changes

Describe your proposal in the issue thread, including the plan, tests, and documentation. For new documentation pages, propose a Diátaxis category.

Create a development branch

Sync and create a new branch:

git fetch upstream
git checkout -b <new-branch-name>

Name your branch <ticket-id>-<description> (e.g., issue-235-add-string-sanitizer), keeping it under 80 characters.

Make your changes

Follow these guidelines:

  • Use separate commits for each logical change, and for changes to different components
  • Keep the Sphinx Stack minimal by default; optional features are best implemented by the projects using the Sphinx Stack rather than the Sphinx Stack itself

Commit a change

git add -A
git commit

Use Conventional Commits format:

feat: add text sanitizer

To determine the commit type, check the file history with git log --oneline <filename>.

Tip

If you're unsure which type to use, the commit may be doing too much, so split it into smaller commits instead. Select the highest-ranked type that fits:

  • ci
  • build
  • feat
  • fix
  • perf
  • refactor
  • style
  • test
  • docs
  • chore

Sign your commits

All commits require cryptographic signatures (DCO 1.1). You can sign commits by adding -S to the git commit command from the previous section, for example:

git commit -S -m "feat: add logging levels to updage script"

Signed commits display a "Verified" badge in GitHub. Set up signing via GitHub Docs - About commit signature verification.

Tip

You can configure your Git client to sign commits by default for any local repository by running git config --global commit.gpgsign true. Once you have done this, you no longer need to add -S to your commits explicitly.

See GitHub Docs - Signing commits for more information.

If you've made an unsigned commit and encounter the "Commits must have verified signatures" error when pushing your changes to the remote:

  1. Amend the most recent commit by signing it without changing the commit message, and push again:

    git commit --amend --no-edit -n -S
git push

  2. If you still encounter the same error, confirm that your GitHub account has been set up properly to sign commits as described in the GitHub Docs - About commit signature verification.

    Tip

    If you use SSH keys to sign your commits, make sure to add a "Signing Key" type in your GitHub account. See GitHub Docs - Adding a new SSH key to your account for more information.

Test the change

Build and run the checks locally before submitting:

cd docs
make html
make spelling      # Check spelling
make linkcheck     # Validate links
make woke          # Check inclusive language
make lint-md       # Check Markdown style
make vale          # Check style guide compliance (optional)

To preview locally with live reload at http://127.0.0.1:8000, run:

make run

Document the change

This documentation is sourced from canonical/sphinx-stack-docs and uses Diátaxis. For small changes, update existing how-to guides and references. For major changes or new flows, create new pages in the appropriate category.

Run the same basic checks locally that GitHub runs on PRs; see Test the change.

Changelog guidance

Ensure that feature changes and fixes are documented in the relevant release notes.

Push the branch and open a PR

git push -u origin <branch-name>

Next, open a PR on GitHub. Format its title as a conventional commit (GitHub may do this automatically for single-commit branches).

Describing PRs

Your PR should include the following details:

  • Title: Short, descriptive summary
  • Description: Problem solved, features added, or bugs fixed
  • Relevant issues: Link related issues and PRs
  • Testing: How reviewers can verify the change or test the fix
  • Reversibility: For costly-to-reverse decisions, explain reasoning and reversal steps

CI/CD pipeline

The repository configures multiple automated checks. Some are conditional based on target branch or changed files.

If a check fails, review the logs for remediation guidance. For failures unrelated to your changes, rebase against the latest base branch.

Checks on all PRs

These run on every PR and on pushes to main:

  • Documentation build: Builds the documentation and checks for errors
  • Spelling check: Verifies spelling using Vale
  • Link check: Validates all links in the documentation
  • Inclusive language check: Runs woke to check for non-inclusive language
  • Python dependency build: Verifies dependencies can be built from source

Checks on PRs to main only

  • CLA check: Verifies you have signed the Canonical Contributor License Agreement
  • Removed URLs check: Detects if any URLs were removed without redirects

CLA check in CI

When you open a pull request (PR) against the main branch, a mandatory automated check verifies that you have signed the CLA. It uses the canonical/has-signed-canonical-cla GitHub Action.

If you haven't signed the CLA:

  1. The check will fail with a message indicating the CLA requirement
  2. Visit https://ubuntu.com/legal/contributors to review and sign the agreement
  3. Once signed, re-run the check if you have permissions, or ask a maintainer to do so. Pushing a new commit also triggers re-evaluation.

The CLA check only runs on PRs to main. Internal team members working on other branches should ensure they have signed the CLA before their changes are merged to main.

Checks on changes to docs/ only

  • Markdown style check: Runs pymarkdownlnt on Markdown files
  • Automatic documentation checks: Runs upstream documentation workflow checks.The project uses canonical/documentation-workflows for automatic documentation checks. To modify this part of CI behavior, pass inputs to upstream workflows rather than creating or customizing local copies.

Optional checks (allowed to fail)

  • Style guide check (vale): Checks compliance with the Canonical style guide
  • Accessibility check (pa11y): Checks accessibility of generated HTML

Review process

PRs are typically reviewed within a week.

Responding to feedback

Push additional commits to address feedback (commit locally rather than via GitHub UI to avoid sync conflicts).

Rebase your branch before requesting a review to keep your commits clean. Once review has started, avoid rebasing to maintain the review history and make it easier for reviewers to see what changed.

Common feedback themes

Reviewers may request:

  • Wording, terminology, or formatting changes
  • Consistency with existing patterns
  • Proper reST or MyST markup style
  • Minimal examples before listing options
  • Cross-references: Use proper reST or MyST syntax
  • Examples: Start minimal, then show options; include verification steps
  • Theme compatibility: Test in both light and dark modes