Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
65 lines (44 loc) · 3.15 KB

CONTRIBUTING.md

File metadata and controls

65 lines (44 loc) · 3.15 KB

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.