Contributor guidelines

Developer prerequisites

pre-commit

Refer to pre-commit for installation instructions.

TL;DR:

curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
uv tool install pre-commit                        # Install pre-commit
pre-commit install                                # Install hooks

Installing pre-commit ensures all contributions adhere to the project’s code quality standards.

Code standards

ruff and doc8 are triggered automatically by pre-commit.

To run checks manually:

make doc8
make ruff

Virtual environment

uv sync
uv pip install -e .[all]

Testing

All tests must be run inside Docker. This prevents accidental extraction of malicious test archives from reaching the host filesystem.

make docker-test

To test a single environment:

make docker-test-env ENV=py312

For an interactive shell inside the container:

make docker-shell

In any case, GitHub Actions runs the full matrix automatically on every push.

Releases

Build the package for releasing:

make package-build

Test the built package:

make check-package-build

Make a test release (test.pypi.org):

make test-release

Release (pypi.org):

make release

Adding tests

  • All test archives must be crafted programmatically in conftest.py using Python’s tarfile module. Do not commit pre-built .tar files.

  • Every new security check must have a corresponding test in the relevant test_*.py file.

  • Integration tests must verify that no partial files remain on disk after a security abort (atomic write contract).

Pull requests

Open a pull request to the dev branch only. Never directly to main.

Note

Create pull requests to the dev branch only!

Examples of welcome contributions:

  • Fixing documentation typos or improving explanations.

  • Adding test cases for new edge cases.

  • Extending support for additional archive attack vectors.

  • Improving error messages.

General checklist

  • Does your change require documentation updates?

  • Does your change require new tests?

  • Does your change add any external dependencies? If so, reconsider: safetar is intentionally dependency-free.

When fixing bugs

  • Add a regression test that reproduces the bug before your fix.

When adding a new feature

  • Update README.rst (quick start, default limits table if relevant).

  • Update ARCHITECTURE.rst if the architectural design changes.

  • Add appropriate tests in the correct test_*.py file.

GitHub Actions

Tests run on Python 3.10–3.14 (all non-EOL versions). See the versions manifest for the full list of available Python versions.

Questions

Ask on GitHub discussions.

Issues

Report bugs or request features on GitHub issues.

Do not report security vulnerabilities on GitHub. Contact the author directly at artur.barseghyan@gmail.com.

View llms.txt version