mirror of
https://github.com/borgbackup/borg.git
synced 2026-05-24 02:55:30 -04:00
66 lines
3.1 KiB
Markdown
66 lines
3.1 KiB
Markdown
|
# 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.
|