Aam Digital is built in the open because we believe in building things together and letting people benefit from and adapt things rather than everybody reinventing their own wheel.
To build great software for small social impact organisations, we welcome anybody willing to contribute. We are a small core team of full-time developers as well as a few regular volunteer contributors. Whether you want to extend our code for your own use case or just help out - we welcome any contributions to make this project better!
This is the default contribution guide for the repositories of the Aam-Digital organisation.
A repository can replace it with its own CONTRIBUTING.md; its README describes how to run, test and lint it.
- The repository's README explains how to run it locally and how to run its tests.
- The Developer Documentation of the main application gives an overview of the architecture, and its Tutorial walks you through the setup and the technologies involved.
- Don't hesitate to ask questions!
Comment on an issue, or open one yourself, also to ask a question. For more general discussions or questions, use the Discussions section. Within the team we also use Slack. Write us an e-mail to get an invitation to our workspace.
Security vulnerabilities are not reported through issues; see the security policy.
Have a look at our issues. Some of them are marked as suitable for a new contributor: Community Help Wanted.
Before you start working on an issue, please always comment on it first to help us coordinate. We will then assign you to the issue and set its status in the project to "In Progress" (as an outside contributor you may not have the permission to assign yourself at first).
We organise our work in the Project Board, which covers the issues of all our repositories:
- Issues move through the columns of the board based on their status, and are sorted by priority (most important on top).
- Please do not work on issues in the "Triage / Analysis" status: these still need a clearer definition and approval from the core team.
- Issues have a type (Bug, New Feature, Task, ...); labels add a status or area.
We follow the GitHub Flow: every change is made on its own branch and merged into the default branch through a pull request.
- Discuss the bug or feature in its issue first, including possible approaches.
- Create a new branch from the current default branch for each issue, with a descriptive name. Do not use the same branch for several features or fixes.
- Make commits on this branch with descriptive messages.
- Run the repository's tests and linting (see its README) and add tests for your change where it makes sense. All checks must pass before your contribution can be accepted.
- Open a pull request once you are done or want feedback. Use the "Draft" state while it is still work in progress.
- The PR title must follow Conventional Commits
(e.g.
fix(export): handle empty values,feat!: ...for a breaking change). PRs are squash-merged with the PR title as the commit message, and the next version number and the release notes are derived from these titles. - Reference the issue in the description (e.g.
closes #15).
- The PR title must follow Conventional Commits
(e.g.
- A different developer reviews your PR. Discussions about the code take place in the PR; please follow it and
explain or adapt your code where necessary.
For repositories that build a container image, each PR gets an image tagged
pr-<number>for testing. - A core team member merges the PR after the review. The branch is deleted automatically.
Depending on the repository, each merge into the default branch is either released right away, or published as a
prerelease (e.g.
1.4.0-edge.3, image tagedge) until the team creates the next full release (image tags<version>,latestandstable).
Please note that by contributing, you make your work available under the license of the repository you
contribute to (see its LICENSE file).