From 379ccaef14f2fc28489a6713c43f08387eff4139 Mon Sep 17 00:00:00 2001 From: Jan Klare Date: Thu, 19 Nov 2026 09:56:02 +0000 Subject: [PATCH] developer-guide: add contribution workflow The developer guide only had a paragraph that pointed contributors to GitHub's pull request documentation. The rest of the process was spread over the style guide (commit messages) and the Zuul CI page, and some of it was not written down anywhere, such as where to branch, which linters CI runs and who merges a pull request. Replace that paragraph with a "Contribution workflow" section that lists the steps in order: 1. Open an issue in the repository where the problem exists. Use osism/issues only if it is not yet clear which repository is affected, or if several repositories are affected. 2. Create a branch: external contributors use a fork, OSISM team members push to the repository in the osism organization. 3. Commit, following the commit message guidelines. This step also points out our rules for transparency about AI assistance: an AI-assisted change gets an Assisted-by trailer naming the assistant, and Signed-off-by, from the responsible person, stays the last line and is never used for an AI assistant. It links to the full rules in the style guide. 4. Open a pull request against the default branch. 5. Pass the CI checks, including the zuul label for long-running jobs. This step names the linters the checks run (ansible-lint, yamllint, flake8, python-black, mypy, hadolint, depending on the repository) and where their configuration files are. Whether to run them locally is left to the contributor. 6. Review and merge: at least one OSISM maintainer approves, and that maintainer also merges. The section does not say when the merge happens, because that can depend on ongoing release processes. The steps link to the existing style guide and Zuul CI pages instead of repeating them. The two GitHub documentation links now point to their current URLs instead of the old ones that redirect. The page intro said that the issue tracker is osism/issues and linked "open an issue" straight to osism/issues/issues/new. Update it to the same rule as step 1. This also removes that link, which redirects visitors who are not logged in to the GitHub login page. The intro also says that we can only fix problems we know about, to encourage reporting issues even if they seem minor. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Jan Klare --- docs/guides/developer-guide/index.md | 41 ++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/guides/developer-guide/index.md b/docs/guides/developer-guide/index.md index 9b786dcb70..f137efbb31 100644 --- a/docs/guides/developer-guide/index.md +++ b/docs/guides/developer-guide/index.md @@ -5,18 +5,43 @@ sidebar_position: 60 # Developer Guide -We welcome any issues, change requests or general feedback. Do not hesitate to [open an issue](https://github.com/osism/issues/issues/new). +We welcome any issues, change requests or general feedback. Do not hesitate to open an issue: we can only +fix problems that we know about, so please report them even if they seem minor. -We use GitHub Issues to capture feature requests, feedback, bugs, etc. The tracker is available in the -[osism/issues](https://github.com/osism/issues/issues) repository. There are no specific requirements for the creation of an issue. +We use GitHub Issues to capture feature requests, feedback, bugs, etc. Open an issue in the repository where +the problem exists. If it is not yet clear which repository is affected, or if several repositories are affected, +use the [osism/issues](https://github.com/osism/issues/issues) repository. There are no specific requirements for the creation of an issue. Error cases should be described in such a way that they are directly reproducible. The more outputs there are, the better. -We use GitHub pull requests for contributions. The use of pull requests is documented in the -official [GitHub documentation](https://docs.github.com/en/pull-requests). -The process in detail for the creation of a fork, branch etc. is also documented in the -official [GitHub documentation](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests). -It is recommended to use the [GitHub CLI](https://cli.github.com). Makes many steps easier. +## Contribution workflow + +We use GitHub pull requests for contributions. How pull requests work is documented in the +official [GitHub documentation](https://docs.github.com/en/pull-requests). It is recommended +to use the [GitHub CLI](https://cli.github.com), which makes many of the following steps easier. + +1. **Open an issue.** Describe the bug or the feature first, so that the change can be discussed before + you start working on it. Open the issue in the repository where the problem exists. Use + [osism/issues](https://github.com/osism/issues/issues) only if it is not yet clear which repository + is affected, or if several repositories are affected. +2. **Create a branch.** External contributors work on a branch in their own fork of the repository, as + described in the [GitHub documentation](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests). + Members of the OSISM team push their branch directly to the repository in the `osism` organization. +3. **Commit your changes.** Follow the [commit message guidelines](./style-guide.md#commit-messages). + Every commit needs a `Signed-off-by` trailer from the person who takes responsibility for the change. + We are transparent about AI assistance: if an AI coding assistant helped create a change, add an + `Assisted-by` trailer that names the assistant, as described in + [Attribution for AI-assisted changes](./style-guide.md#attribution-for-ai-assisted-changes). + `Signed-off-by` is always the last line and is never used for an AI assistant. +4. **Open a pull request.** Open it against the default branch of the repository and link the issue + it addresses. +5. **Pass the CI checks.** All CI checks of the pull request must pass. Most repositories run them in + [Zuul CI](./zuul.md). Depending on the repository, the checks include linters such as `ansible-lint`, + `yamllint`, `flake8`, `python-black`, `mypy` and `hadolint`. Their configuration files, for example + `.ansible-lint`, `.yamllint.yml` and `.flake8`, are in the root of each repository. Some long-running + jobs only start once the [`zuul` label](./zuul.md#the-zuul-label) has been assigned to the pull request. +6. **Review and merge.** At least one OSISM maintainer reviews the pull request. The maintainer who + approves it also merges it. ## How to add a new service