Spaces:
Running
Running
| # 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](CODE_OF_CONDUCT.md). By participating you agree to uphold it. Report unacceptable behaviour to the maintainers. | |
| ## How to report an issue | |
| 1. Search existing [issues](https://github.com/) 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: | |
| ```bash | |
| 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](https://peps.python.org/pep-0008/). 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](docs/system-requirements.md) for hardware and software requirements, and the project [README](README.md) for the basic quickstart. | |
| ## Architecture decisions | |
| Non-obvious design choices are documented as Architecture Decision Records (ADRs) under [docs/architecture/adrs/](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. | |