Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (102 loc) · 5.2 KB

CONTRIBUTING.md

File metadata and controls

139 lines (102 loc) · 5.2 KB
Raw

Contributing to autoguardrails

Thanks for your interest in contributing! This project is a small alignment research scaffold: a stdlib-only Python harness (autoguardrails/) that searches over a single mutable policy.md surface against a fixed evaluation suite. Contributions of all kinds are welcome: bug reports, documentation, harness improvements, and additional benign/attack eval cases.

By participating, you agree to abide by our Code of Conduct.

Ways to contribute

The research contract (read before changing the harness)

autoguardrails only works as a comparison tool if the evaluation surface stays fixed between runs. Please respect these boundaries:

  • policy.md is the only file expected to change between baseline and candidate runs.
  • eval_suite.jsonl and judge_prompt.md are frozen. If you change them, you start a new experiment lineage — say so explicitly in your PR, and do not compare the new numbers against old results.tsv rows.
  • The harness enforces this with a protected-surface manifest; PRs that loosen that guarantee need an explicit rationale.

Pull Request Process

For External Contributors

  1. Fork the repository to your GitHub account.
  2. Create a branch from main with a descriptive name: 
    git checkout -b feature/add-attack-family
  3. Make your changes following the Code Style guidelines.
  4. Add tests for any new functionality.
  5. Update documentation if your changes affect the CLI or the research contract.
  6. Commit with clear messages following Conventional Commits: 
    feat: add a cyber attack family to the stub classifier
fix: restore policy.md when a candidate is rejected
docs: clarify the benign-pass floor
  7. Push your branch and open a Pull Request against main.
  8. Sign the CLA when prompted by the CLA Assistant bot.
  9. Wait for review — a maintainer will review your PR within 2 weeks (SLA).

For Internal Contributors (Santander)

  1. Create a branch from main (no fork needed if you are a member of the org).
  2. Follow steps 3-7 above.
  3. Request review from the maintainer team in CODEOWNERS.

PR Requirements

All pull requests must pass the following automated checks before merge:

  • CI lint and tests (ci) — Linting, formatting, type-check, unit tests
  • Security scan (codeql, dep-scan) — SAST and dependency audit
  • License check (license-check) — SPDX headers + no runtime-dependency creep
  • Pattern check (pattern-check) — No internal URLs, IPs, or corporate email addresses
  • CLA signed (for external contributors)

Additionally:

  • At least 1 maintainer approval is required.
  • All review conversations must be resolved.
  • The branch must be up to date with main.

Code Style

Python

  • Follow PEP 8.
  • Use Black for formatting (line length: 100).
  • Use Ruff for linting.
  • Use mypy for type checking.
  • All public functions and classes must have docstrings (Google style).
  • Keep the harness dependency-free (Python standard library only).

File Headers

Every source file must include the copyright header:

# Copyright (c) 2026 Santander Group
# SPDX-License-Identifier: Apache-2.0

Commit Messages

Follow Conventional Commits:

Prefix Use
feat: New feature
fix: Bug fix
docs: Documentation only
test: Adding or updating tests
refactor: Code refactoring (no feature/fix)
ci: CI/CD changes
chore: Maintenance tasks

Testing

  • Write tests for all new functionality.
  • Use pytest as the test framework.
  • Place tests in the tests/ directory, mirroring the source structure.
  • Run the full test suite before submitting a PR: 
    pytest tests/ -v --cov=autoguardrails
  • Minimum code coverage target: 80%.

Contributor License Agreement (CLA)

By submitting a pull request, you agree to the terms of our Contributor License Agreement. The CLA Assistant bot will automatically check your PR and ask you to sign the CLA if you have not already done so.

The CLA ensures that contributions can be distributed under the project's Apache 2.0 license.

Release Process

This project follows Semantic Versioning (SemVer):

  • MAJOR — Incompatible API changes
  • MINOR — New features (backward-compatible)
  • PATCH — Bug fixes (backward-compatible)

Releases are managed by maintainers. If you believe a release is warranted, open an issue to discuss.

Thank you for contributing to autoguardrails!