borgbackup/CONTRIBUTING.md

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.

How to Contribute

1. Discuss Changes: Before starting major work, please discuss your proposed changes on the GitHub issue tracker. 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 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.

Security

If you discover a security vulnerability, please follow our Security Policy for reporting it.