mirror of
https://github.com/borgbackup/borg.git
synced 2026-05-22 18:16:02 -04:00
e2a651c684
Some checks failed
CI / lint (push) Has been cancelled
CI / security (push) Has been cancelled
CI / asan_ubsan (push) Has been cancelled
CI / native_tests (push) Has been cancelled
CI / vm_tests (Haiku, false, haiku, r1beta5) (push) Has been cancelled
CI / vm_tests (NetBSD, false, netbsd, 10.1) (push) Has been cancelled
CI / vm_tests (OmniOS, false, omnios, r151056) (push) Has been cancelled
CI / vm_tests (OpenBSD, false, openbsd, 7.8) (push) Has been cancelled
CI / vm_tests (borg-freebsd-14-x86_64-gh, FreeBSD, true, freebsd, 14.3) (push) Has been cancelled
CI / windows_tests (push) Has been cancelled
65 lines
3.1 KiB
Markdown
65 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.
|