CONTRIBUTING.md

Contributing to Audit Assistant

Thanks for your interest in improving the Audit Assistant. This document explains how to report issues, propose changes, and submit pull requests.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating you agree to uphold it. Report unacceptable behaviour to the maintainers.

How to report an issue

1. Search existing issues to confirm the problem hasn't already been raised.
2. Open a new issue with:
   • A clear, descriptive title.
   • What you expected to happen.
   • What actually happened.
   • Steps to reproduce (a minimal example helps).
   • Environment details (Python version, OS, deployed vs local).
   • Any relevant logs, stack traces or screenshots.

For security-sensitive issues (credentials, data leakage), do not open a public issue — contact the maintainers directly.

How to propose a change

For non-trivial changes, open an issue first to discuss the approach before writing code. This avoids wasted effort if the change conflicts with planned work or the project's direction.

For small, self-contained fixes (typos, bug fixes, doc improvements) you can go straight to a pull request.

Pull request workflow

1. Fork the repository and create a feature branch off main:
   • Branch naming: fix/<short-description> for bug fixes, feat/<short-description> for new features, docs/<short-description> for documentation-only changes.
2. Make your changes, keeping the diff focused. One PR = one logical change.
3. Run the test suite locally and confirm it passes:

   pytest tests/
   

4. Update documentation under docs/ if your change affects architecture, runbook procedures, or supported configuration.
5. Commit with a clear message describing what changed and why (not how — the diff shows how).
6. Push your branch and open a pull request against main.
7. In the PR description:
   • Link any related issues (Closes #123).
   • Summarise the change in one or two sentences.
   • Note any breaking changes, migration steps, or follow-up work.

PRs are reviewed by the maintainers. Expect feedback, requests for revisions, or questions. The goal is a system that's maintainable by anyone who picks it up later, not just by you.

Code style

• Python: follow PEP 8. Use type hints on new function signatures.
• Imports: group standard library, third-party, local — separated by blank lines.
• Docstrings: required on public modules, classes and functions. Use the Google or NumPy docstring style — pick one and stay consistent within a file.
• No commented-out code in commits. Delete it; git history preserves it if you need it back.
• No internal IPs, credentials, or environment-specific URLs in committed configuration. Use environment-variable placeholders (e.g. ${OLLAMA_BASE_URL}).

Development setup

See docs/system-requirements.md for hardware and software requirements, and the project README for the basic quickstart.

Architecture decisions

Non-obvious design choices are documented as Architecture Decision Records (ADRs) under docs/architecture/adrs/. If your change introduces or changes a significant design decision, add a new ADR following the same template.

Questions

If anything in this document is unclear, open a discussion or an issue. We'd rather answer questions than have contributors guess.