Adopt AIND Coding Standards

# AIND coding standards audit checklist

Audit date: 2026-06-27

Repository audited:

- Upstream: https://github.com/AllenNeuralDynamics/aind-torch-utils
- Audited commit: `60c9c08e1ec5a1eacf49861ad45559c87725974c`
- `git fetch` confirmed local `HEAD`, `origin/main`, and `origin/dev` all point
to the same commit.

Standards sources:

- AIND software practices:
https://docs.allenneuraldynamics.org/en/latest/policies_practices/software_practices.html
- AIND documentation guidelines:
https://docs.allenneuraldynamics.org/en/latest/policies_practices/docs.html

Legend:

- `[x]` means implemented based on local files or public GitHub/PyPI evidence.
- `[ ]` means not implemented, partially implemented, or requiring manual/private
verification before it can be checked off.
- "Partial" means some evidence exists, but the standard is not fully met.
- "Manual verification" means public/local access was not enough to determine
compliance.

## Summary

- The package has tests, docs, issue templates, tags, branch protection on
`main` and `dev`, a license, and some AIND reusable release automation.
- The largest gaps are current AIND tooling alignment: `uv` is not consistently
used, `ruff` is not configured or run in CI, docs use Sphinx instead of
MkDocs/mkdocstrings, coverage thresholds are `0`, GitHub Releases are absent,
and the package name keeps the older `aind-` prefix.

## Templates and governance

- [ ] Partial: Use the appropriate AIND template for new repositories.
Evidence: the repo has several template-like files, but current configuration
uses Sphinx, `black`, `flake8`, `interrogate`, and `pip`-style commands rather
than the current `aind-library-template` stack of `uv`, `ruff`, and MkDocs.

- [ ] Document any approved deviations in `pyproject.toml` or GitHub Actions.
Evidence: no explicit deviation notes were found in `pyproject.toml` or
workflow files.

## Package management

- [ ] Package management must be handled by `uv`.
Tracked README, CONTRIBUTING, and CI use `pip` commands. No tracked `uv.lock`
is present.

- [ ] Use `uv` commands in developer docs and CI.
Evidence: README uses `pip install -e . --group dev`; CI uses
`python -m pip install -e . --group dev --no-cache-dir`.

## Style, linting, docstrings, and typing

- [ ] Use `ruff` to enforce coding standards.
Evidence: `ruff` is not listed in dev dependencies, no `[tool.ruff]` config
exists, and CI does not run `ruff`.

- [ ] Configure `ruff` line length explicitly in `pyproject.toml`.
Evidence: no `[tool.ruff]` section exists. `black` is configured with
`line-length = 88`.

- [ ] Use `ruff check` and optionally `ruff check --fix`.
Evidence: CONTRIBUTING documents `flake8`, `black`, `isort`, and
`interrogate`, but not `ruff`.

- [ ] Optional: add `ruff-pre-commit` for automatic checks.
Evidence: no `.pre-commit-config.yaml` exists.

- [ ] Follow PEP 8 with maximum line length of 100 characters.
Evidence: tracked files have lines over 100 characters, including
`src/aind_torch_utils/config.py`, `src/aind_torch_utils/run.py`,
`examples/run_proteomics_example.py`, `README.md`, and workflow/docs files.

- [ ] Follow PEP 257 docstrings in NumPy format.
Evidence: `uvx interrogate -vv src tests examples benchmarking` reports
74.2% docstring coverage. `uvx ruff check ... --select ANN,D,C901,E501`
reported many docstring-format issues.

- [ ] Require function parameter and return type annotations.
Evidence: source files are mostly typed, but annotations are missing in
`src/aind_torch_utils/accumulators.py`, tests, examples, and helper
functions. There is no CI enforcement for annotations.

- [ ] Fix current default `ruff` findings.
Evidence: `uvx ruff check src tests examples benchmarking --line-length 100`
found unused imports in `src/aind_torch_utils/run.py` and
`src/aind_torch_utils/workers.py`.

## Tests and coverage

- [x] Use `pytest` for unit tests.
Evidence: tests are present under `tests/`, and CI runs
`coverage run -m pytest -q`.

- [ ] Enforce 100% test coverage.
Evidence: `[tool.coverage.report] fail_under = 0`; README badge says
coverage is 18%.

- [ ] Run tests before merging pull requests into both `main` and `dev`.
Evidence: `.github/workflows/test_and_lint.yml` runs on pull requests to
`main` only, not `dev`.

- [ ] Make CI fail when coverage is below the standard.
Evidence: CI runs `coverage report` but does not set a nonzero threshold.

- [ ] Fix badge-update workflow coverage command.
Evidence: `tag_and_publish.yml` uses `coverage run -m unittest discover`,
while the project tests are pytest tests.

- [ ] Verification limitation: run the full pytest coverage suite locally.
Evidence: a local `uv run --group dev coverage run -m pytest -q` attempt
could not complete because extracting the PyTorch wheel exhausted disk space.

## GitHub automation

- [ ] Partial: Use AIND reusable workflows for GitHub automation.
Evidence: release tagging uses
`AllenNeuralDynamics/.github/.github/workflows/release-bump-version.yml@main`,
but lint/test CI is a custom workflow.

- [ ] Update lint/test CI to the current AIND reusable workflow pattern.
Evidence: CI manually installs dependencies and runs `interrogate` plus
pytest coverage.

- [x] Dependabot is configured.
Evidence: `.github/dependabot.yml` checks `pip` and `github-actions` weekly.

## Documentation

- [ ] Use MkDocs with mkdocstrings for project documentation.
Evidence: docs use Sphinx, `sphinx.ext.autodoc`, `sphinx.ext.napoleon`,
and the Furo theme. No `mkdocs.yml` or `mkdocstrings` dependency exists.

- [ ] Host documentation through Read the Docs.
Evidence: no root `.readthedocs.yaml` exists, and the Read the Docs API
returned "No Project matches the given query" for `aind-torch-utils`.

- [x] Keep documentation source in root-level `docs/`.
Evidence: tracked docs live under `docs/source`.

- [x] Keep examples in root-level `examples/`.
Evidence: tracked examples live under `examples/`.

- [ ] Provide README standard headers: Usage, Level of Support, Installation.
Evidence: README has Installation and usage-like sections, but no
"Level of Support" section.

- [ ] Include a beginner tutorial.
Evidence: `docs/source/getting-started.rst` and README include examples, but
the docs are not in the required MkDocs stack and do not clearly separate a
beginner tutorial.

- [ ] Include how-to guides for specific use cases.
Evidence: CLI and getting-started docs exist; no dedicated how-to guide set
was found.

- [ ] Include auto-generated technical reference for fully released packages.
Evidence: Sphinx auto-generates API docs via `sphinx-apidoc`, but the required
MkDocs/mkdocstrings reference is not implemented.

- [ ] Include explanation of technical or philosophical decisions for fully
released packages.
Evidence: no dedicated explanation/design-rationale section was found.

## Code quality recommendations

- [ ] Keep function complexity at 10 paths or fewer.
Evidence: `.flake8` sets `max-complexity = 10`, but CI does not run flake8.
Ruff complexity checks found functions over 10 paths, including
`benchmarking/plot_gpu_metrics.py::main`,
`benchmarking/plot_metrics.py::plot_system`, and
`src/aind_torch_utils/workers.py::WriterWorker.run`.

- [ ] Prefer return-early/fail-fast patterns.
Evidence: some validation exists, but no project-wide enforcement or clear
review checklist was found.

- [ ] Keep code analyzable by static analysis tools.
Evidence: partial type hints exist, but no `ruff`, `mypy`, `pyright`, or
comparable static-analysis CI is configured.

- [ ] Keep modules under 1000 lines and functions under 100 lines.
Evidence: modules are under 1000 lines, but several functions exceed 100
lines, including `src/aind_torch_utils/run.py::run`,
`src/aind_torch_utils/run.py::_parse_args`,
`src/aind_torch_utils/workers.py::WriterWorker.run`, and functions in
`examples/run_proteomics_example.py` and benchmarking scripts.

- [ ] Use internal package naming pattern `-` where possible.
Evidence: package name is `aind-torch-utils`.

- [ ] Do not prefix packages with the `aind-` namespace.
Evidence: package name is `aind-torch-utils`.

- [ ] Pin internal dependencies with `==` or with both a floor and ceiling.
Evidence: dependencies include unbounded `torch`, `pydantic`, `psutil`, and
`tensorstore`; `numpy` has only a lower bound; optional `denoise-net` points
to a GitHub `main` branch.

- [x] Unit tests clean up test files or write to temporary folders.
Evidence: TensorStore test data is written under pytest `tmp_path` fixtures.

- [x] Do not store large auto-generated files for unit tests.
Evidence: no large generated test data is tracked.

- [ ] Partial: Keep packages agnostic of runtime infrastructure where possible.
Evidence: the core package is a Python package, but examples and local ignored
Code Ocean files include AWS/S3 and Code Ocean assumptions.

- [ ] Containerized environments should log their dependencies.
Evidence: local ignored Code Ocean `environment/postInstall` does not write
`pip list` or equivalent to `/results`.

## Security

- [x] Do not commit `.env` files.
Evidence: `git ls-files` found no tracked `.env` files, and `.gitignore`
excludes `.env`, `*.env`, and secret-related files.

- [x] Do not hardcode or expose secrets, tokens, or credentials in tracked code.
Evidence: search found workflow references to GitHub Secrets and example code
that obtains AWS session credentials at runtime, but no literal secret values.

- [ ] Manual verification: Access tokens must never be permanent and should last
no longer than 6 months.
Evidence: workflows use `${{ secrets.SERVICE_TOKEN }}`, but token duration is
not visible from public/local files.

## Branch management

- [x] Keep a `main` branch for production-ready code.
Evidence: `main` exists and current commit is tagged `v0.0.9`.

- [x] Use `dev` as the default branch for development and feature integration.
Evidence: `dev` exists, but GitHub reports `main` as the default branch.

- [x] Merge feature branches back into `dev` after review using squash merge.
Evidence: recent PRs target `main`, and history contains merge commits into
`main`.

- [x] Partial: Protect `main` and `dev`.
Evidence: public branch API reports both branches as `protected: true`.
Detailed protection settings require authentication.

- [x] Require at least 1 human review approval before merging into `main` and
`dev`.
Evidence: detailed branch protection rules require authentication. Public
branch summaries show required status-check enforcement as `off`.

## Semantic versioning

- [x] Use semantic version tags of the form `major.minor.patch`.
Evidence: tags `v0.0.1` through `v0.0.9` exist.

- [ ] Partial: Use conventional commits to determine semantic versioning.
Evidence: CONTRIBUTING documents Angular/conventional-style messages, and
some commits/PR titles follow it, but history includes nonconforming messages
and no enforcement was found.

## Releases

- [ ] Use GitHub Releases as the primary release method.
Evidence: Git tags exist, but the GitHub Releases API returns an empty release
list and no latest release.

- [ ] Publish to PyPI if the package has general external use.
Evidence: the PyPI JSON API for `aind-torch-utils` returned 404 Not Found.

- [ ] Include changelogs in each release with links to closed pull requests.
Evidence: no GitHub Release objects were found, so no release changelogs were
found.

## Level of support

- [ ] Add and maintain an AIND support badge in README.
Evidence: README includes license, code style, semantic-release, interrogate,
coverage, and Python badges, but no support badge.

- [ ] Add a README "Level of Support" section matching the support badge.
Evidence: no Level of Support section was found.

## Repository permissions

- [x] Create the repository under the AllenNeuralDynamics GitHub organization.
Evidence: upstream is `AllenNeuralDynamics/aind-torch-utils`.

- [ ] Manual verification: add the appropriate GitHub Team as Maintainer.
Evidence: team permissions are not visible from unauthenticated public API
access.

- [ ] Manual verification: ensure at least one GitHub Team is added to the repo.
Evidence: team permissions are not visible from unauthenticated public API
access.

## Code review process

- [x] Partial: open pull requests and add at least one team member as reviewer.
Evidence: PRs are used. Some PRs requested reviewers, but many public PR
records show zero requested reviewers.

- [ ] Follow the Google Code Review Guide.
Evidence: no repo documentation or template references the guide.

- [ ] Link PRs with an issue that is part of a milestone.
Evidence: some PRs link issues, such as PR #22 resolving issue #20, but the
milestones API returned zero milestones and PRs have `milestone: null`.

- [x] Require code review for every change, regardless of seniority.
Evidence: public history shows PR merges plus automation commits. Detailed
enforcement cannot be verified without private branch-protection data.

- [x] Require at least one other human software developer approval before merge.
Evidence: detailed review requirements require authentication; not confirmed
from public/local evidence.

- [ ] Keep PRs small, around 500 lines of code or fewer.
Evidence: not enforceable from repo configuration; needs process review.

- [ ] Ensure PRs address linked issues and have been tested.
Evidence: issue linking and testing are not consistently enforced by templates
or branch rules visible publicly.

- [ ] Require PR titles into `dev` to follow conventional commit format.
Evidence: PRs currently target `main`, and several titles are not strictly
conventional-commit formatted.

- [x] Use PR descriptions or comments to provide context and review focus.
Evidence: some PRs include detailed context; no template enforces this.

- [ ] Follow up quickly on reviews and review within one day.
Evidence: process expectation; not auditable from repo files.

- [ ] Reviewers verify standards, scope, tests, and version bump.
Evidence: process expectation; no checklist or template enforces this.

## AI-generated code expectations

- [ ] Ensure AI-assisted code still meets all coding standards above.
Evidence: current repo does not meet several standards above.

- [ ] Require AI-assisted code to integrate with existing infrastructure.
Evidence: process expectation; not auditable from repo files.

- [ ] Require authors to understand and justify generated code.
Evidence: process expectation; not auditable from repo files.

- [ ] Require human review before AI-assisted code can merge to `dev` or `main`.
Evidence: human-review enforcement could not be verified from public/local
evidence.

## Non-actionable or TBD standards

- [ ] Track AIND TBD item: structured logging using AIND standard format.
Evidence: standard is marked TBD; no AIND structured logging config found.

- [ ] Track AIND TBD item: update `pyproject.toml` with individual authors.
Evidence: standard is marked TBD; `pyproject.toml` lists one author.

- [ ] Track AIND TBD item: branch-name character limits/category prefixes.
Evidence: standard is marked TBD; no enforcement found.