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
===================

   make create-venv


Installation
============

   make install


Testing
=======

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

   make test

To test a single environment:

   make test-env ENV=py312

For an interactive shell inside the container:

   make 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 "struct" module or "zipfile".  Do not commit pre-
  built ".zip" 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:
  "safezip" 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 "plan.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.