contributing guide incl. AI policy, fixes #9409

2026-05-21 17:41:22 -04:00 · 2026-05-15 14:41:36 +02:00 · 2026-05-15 14:41:36 +02:00 · e2a651c684
commit e2a651c684
parent 0a1570f2a8
1 changed files with 65 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,65 @@
+# Contributing to BorgBackup
+
+First of all, thank you for considering contributing to Borg!
+
+This guide provides a brief overview of how to contribute.
+
+For the full, detailed development documentation, please refer to the
+[Development Docs](https://borgbackup.readthedocs.io/en/master/development.html).
+
+## How to Contribute
+
+1.  **Discuss Changes:** Before starting major work, please discuss your proposed changes on the [GitHub issue tracker](https://github.com/borgbackup/borg/issues). Smaller changes can also be discussed in the comments of the pull request.
+2.  **Branching Model:** Most Pull Requests should be made against the `master` branch. Maintenance branches (e.g., `1.4-maint`) are generally reserved for bug fixes and smaller changes.
+3.  **Pull Requests:**
+    - Create a feature branch for your changes.
+    - Keep changesets clean and focused on a single topic.
+    - Reference any related issues in your commit messages.
+    - Ensure your PR includes tests and documentation for new features.
+    - Proof read your PR yourself, fix typos and other obvious issues.
+
+## Responsible AI Usage
+
+You are welcome to use AI tools, but we require that a human is always "in the loop". 
+
+AI-generated content must not be submitted without active critical review, modification, and integration by the human contributor. We require that the final contribution is a product of human creative control and that AI is only used as a supportive tool to assist the human author.
+
+As the contributor, you are responsible for the entire content of your pull request.
+
+This includes:
+- Verifying the correctness and security of any AI-generated code.
+- Ensuring that new or modified code is covered by correct tests.
+- Proofreading and refining any AI-generated documentation or comments.
+- Being able to explain, debug, and maintain the code you submit.
+
+Always be aware of the limitations and the ecological footprint of AI tools and act accordingly:
+- Do not just believe what AI tells you, but verify it critically. AI is known to hallucinate, to be over-confident and to always tell you that you are right, even when you are not.
+- Do not use AI tools for tasks that can be done more efficiently manually or by simpler tools.
+- Learn how to use AI tools efficiently.
+
+## Development Setup
+
+Borg is written in Python with some Cython/C. To set up a development environment:
+
+1.  Create and activate a virtual environment.
+2.  Install development dependencies: `pip install -r requirements.d/development.lock.txt`
+3.  Install borg in editable mode: `pip install -e .`
+4.  Install pre-commit hooks: `pre-commit install`
+
+## Code Style
+
+We use [Black](https://black.readthedocs.io/) for automated code formatting.
+- Install black: `pip install -r requirements.d/codestyle.txt`
+- Check formatting: `black --check .`
+- Apply formatting: `black .`
+
+## Running Tests
+
+We use `tox` and `pytest` for testing.
+- Run all tests: `tox`
+
+For more advanced testing options (including Vagrant and Podman), see the full [Development documentation](https://borgbackup.readthedocs.io/en/master/development.html).
+
+## Security
+
+If you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) for reporting it.