Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (95 loc) · 4.98 KB

CONTRIBUTING.md

File metadata and controls

150 lines (95 loc) · 4.98 KB
Raw

Contributing to AssetOpsBench

Thank you for your interest in contributing to AssetOpsBench! This project aims to advance the state of Industrial AI by providing a rigorous benchmarking framework for autonomous asset operations.

How to Contribute

  1. Fork the repository to your own GitHub account.
  2. Create a feature branch from main in your fork: git checkout -b feature/<short-topic>.
  3. Keep PRs small and focused: We prefer PRs with fewer than 300 changed lines to ensure high-quality reviews.
  4. Follow Conventional Commits for all commits and PR titles.
  5. Run formatting and tests locally before opening a pull request.
  6. Open a Pull Request from your fork to main with a clear description of the benchmarking impact.

Note: All PRs are merged using Squash and merge. The PR title will become the final commit message. Please write it carefully using the Conventional Commits format.

DCO: Developer's Certificate of Origin

This repository requires a DCO 1.1 signoff on every commit. This is a legal statement asserting that you have the right to submit the code. You can sign off by adding the -s or --signoff flag:

git commit -s -m 'feat(eval): add predictive maintenance scoring for pumps'

If you have already made commits without a signoff, you can fix them:

  • Last commit only: git commit --amend --no-edit --signoff
  • Multiple commits: git rebase --signoff HEAD~<n> (where <n> is the number of commits).

Followed by a git push -f to your fork.

Commit & Branching Standards

Conventional Commits

We follow the Conventional Commits specification.

Structure: <type>[optional scope]: <description>

  • feat: New benchmark scenario, asset model, or agentic logic (e.g., ReAct).
  • fix: Bug fix in evaluation scripts or data loaders.
  • docs: Documentation improvements.
  • refactor: Code changes that neither fix a bug nor add a feature.
  • perf: Improvements to evaluation speed or data processing.

Branch Naming

Use the structure: <type>/<description>

  • Good: feature/hvac-chiller-scenario, bugfix/fix-jsonl-loader
  • Bad: update1, feature_new_stuff (no underscores or vague names)

Local Development Setup

We use uv for lightning-fast Python dependency management.

1. Install Dependencies

uv sync --dev
source .venv/bin/activate

2. Code Quality & Formatting

We use ruff for both linting and formatting. Ruff is not included in the development dependencies, so use uvx to run it in an isolated environment:

uvx ruff check .
uvx ruff format --check .

Full-repository checks can report pre-existing lint and formatting violations. Focus fixes on the Python files you changed, and report unrelated failures separately rather than reformatting the whole repository in your PR.

3. Security Scanning

This repo blocks secrets (API keys, tokens, credentials) at three layers: a local pre-commit hook, a CI workflow, and GitHub push protection. As a contributor you only need to set up the local hook once per clone:

uv pip install pre-commit detect-secrets
pre-commit install

After this, every git commit automatically runs gitleaks and detect-secrets on your staged changes and aborts the commit if a secret is found. To scan the whole repo on demand:

pre-commit run --all-files

If you add a new file that legitimately contains an example/placeholder value flagged as a secret, update the detect-secrets baseline and audit it:

detect-secrets scan --baseline .secrets.baseline
detect-secrets audit .secrets.baseline

Known, already-triaged historical findings are listed in .gitleaksignore (by fingerprint). Never add a real secret there — if a live credential is detected, rotate/revoke it at its source first, then remove it from the code.

The same scans run in CI on every pull request, so a commit that slips past the local hook will still be caught before merge.

Running Tests & Validation

Unit Tests

Validate core logic for metrics and data parsing:

uv run pytest src/ -k "not integration"

Full Suite / Integration Tests

Run the full suite (integration tests may require external services):

uv run pytest src/

See INSTRUCTIONS.md for integration prerequisites and narrower test commands. The unit test command above does not require CouchDB or WatsonX.

Pull Request Guidelines

  • Benchmark Integrity: If your change modifies existing scoring logic, please include a "Before vs. After" comparison in the PR description.
  • Asset Privacy: Ensure no real-world sensitive telemetry data is included in scenarios without anonymization.
  • Documentation: Update the relevant dataset cards (e.g., for FailureSensorIQ) if you modify the underlying data structures.
  • PR Templates: Use the provided templates for Features, Bug Fixes, or Chores to ensure consistent review cycles.