Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 33 additions & 8 deletions docs/guides/developer-guide/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down