Contributing¶
Thank you for your interest in Abilian SBE. Contributions of every size are welcome: a bug report, a fix to a page of this documentation, a translation, a new feature. Everyone taking part is expected to act with courtesy and respect.
Ways to contribute¶
- Report a bug or ask for a feature on the issue tracker. Say what you did, what you expected and what happened instead, with the version and, for a problem in the interface, a screenshot.
- Improve the documentation. It lives in
docs/, in Markdown: the English pages indocs/src/, their French translations indocs/i18n/fr/. - Translate the interface. The catalogs are in
src/abilian/sbe/translations/andsrc/abilian/translations/, one per language. - Change the code, through a pull request.
Architecture Decision Records¶
Significant changes to the architecture are discussed and recorded as Architecture Decision Records (ADRs), in notes/adrs/. Read the ones that touch your change before you start. A new feature or a change to how the parts fit together should refer to an ADR, or propose one.
Making a change¶
- Discuss first anything larger than a fix: open an issue, or comment on an existing one, so that the work is not done twice and the approach is agreed on.
- Fork the repository and set it up as the developer guide explains.
- Work on a branch named after what it does, for instance
fix/upload-timeoutorfeat/calendar-export. - Add tests. A new feature comes with tests; a bug fix comes with a test that fails without it. Unit tests go in
tests/a_unit/, those that need the application or the database intests/b_integration/, the browser tests intests/c_e2e/ande2e_playwright/. -
Check your work before you push:
make format # ruff format and ruff check --fix make lint # the linters and the import contracts make test # the test suite make test-e2e # if you changed a pageThe pre-commit hooks, installed by
make install, run the quick checks on every commit. -
Update the documentation when your change shows in the interface or in the configuration, in English and, if you can, in French.
- Open the pull request. Explain what it changes and why, and link the issue. Maintainers review it; expect questions and requests for changes.
Conventions¶
- Python 3.12 or later, with type hints on every function.
- Formatting is ruff's: run
make formatand do not argue with it. - Linters are not silenced: no
noqa, notype: ignore. If a rule gets in the way, change the code, or discuss the rule. - Logging goes through loguru:
from loguru import logger. - Interface text is written to be translated, with
_()in Python and in templates, and the pages use the components of the Abilian Design System. - Commit messages follow Conventional Commits:
fix(documents): keep the owner when moving a folder. A short subject line, and if needed one paragraph that says why.
Licence¶
Abilian SBE is licensed under the LGPL v3. By contributing, you agree that your contribution is released under the same licence. The project follows the REUSE specification: REUSE.toml declares the copyright and licence of every file. A file that comes from elsewhere, under another licence, says so in a comment at its top.
Questions¶
Ask on the issue tracker. There is no wrong question.