From c305dfa2c47a3d175c50713203b95e712bd85837 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 13 May 2026 14:17:52 +0200 Subject: [PATCH 1/2] contributing guide incl. AI policy, fixes #9409 --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..fb97939ed6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# 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. + +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. From cb1ad25b802e75cc0792a2e5c7b9cafe7e18ca48 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 13 May 2026 21:33:17 +0200 Subject: [PATCH 2/2] fixup --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb97939ed6..32ea9b5d03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,7 @@ 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.