mirror of
https://github.com/borgbackup/borg.git
synced 2026-05-28 04:03:21 -04:00
contributing guide incl. AI policy, fixes #9409
This commit is contained in:
parent
316d774bbd
commit
c305dfa2c4
1 changed files with 64 additions and 0 deletions
64
CONTRIBUTING.md
Normal file
64
CONTRIBUTING.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue