Skip to content

docs: update software style based on WG agreement #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dbirman merged 6 commits into from
Apr 15, 2026
Merged

docs: update software style based on WG agreement #90

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
338255a
docs: update based on Monday discussion
dbirman Apr 14, 2026
f42026b
docs: fix exact pin
dbirman Apr 14, 2026
0939e9d
docs: update deviation section, do not specify deviation details in i…
dbirman Apr 14, 2026
cb7e6d3
docs: add link to conventional commits, simplify complexity standard
dbirman Apr 14, 2026
9d13d56
docs: add pre-commit hook info
dbirman Apr 14, 2026
5a12d3d
docs: update semver section language
dbirman Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 40 additions & 9 deletions docs/source/policies_practices/software_practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,54 @@

## Core principles

All of the teams in Scientific Computing adhere to a set of core principles about our software.
Scientists and engineers are expected to adhere to a set of core principles about our software.

### Code Review
### Style

At least one other software developer needs to approve a pull request in order for it to be merged. Please be courteous when providing feedback. The team lead can resolve any conflicts.
These standards are maintained by the [aind-library-template](https://github.com/AllenNeuralDynamics/aind-library-template). Use the template when creating new packages. Our maintained templates are:
Comment thread
dbirman marked this conversation as resolved.

### Style
| Template | URL |
| --- | --- |
| Python package | https://github.com/AllenNeuralDynamics/aind-library-template |
| Code Ocean capsule | ... |
| Code Ocean pipeline | ... |
| Analysis capsule | ... |

The decision to deviate from these style standards must be made in consultation with an entire team and be manager-approved. Deviations must be implemented by modifying the `pyproject.toml`.

#### Standard

Package management should be handled by [uv](https://docs.astral.sh/uv/).

We use `black`, `flake8`, and `interrogate` to enforce [PEP 8](https://peps.python.org/pep-0008/) standards with [docstrings](https://peps.python.org/pep-0257/) in [NUMPY](https://numpydoc.readthedocs.io/en/latest/format.html) format.
We use [ruff](https://docs.astral.sh/ruff/) to enforce [PEP 8](https://peps.python.org/pep-0008/) standards with [docstrings](https://peps.python.org/pep-0257/) in [NUMPY](https://numpydoc.readthedocs.io/en/latest/format.html) format. Use `ruff check` and `ruff check --fix`. Line lengths should have a maximum of **100** characters.
Comment thread
dbirman marked this conversation as resolved.
Outdated

### Versioning
Releases should follow [semantic versioning](https://semver.org/) with `major.minor.patch` versions. Only external-facing packages should be published to [pypi](https://pypi.org/), internal packages should be installed from github releases. Use the following prefixes to trigger version updates automatically after merges to main:
Copy link
Copy Markdown
Contributor

@seanmcculloch seanmcculloch Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... via automated github action <link to .github workflow for semantic version bump>

Copy link
Copy Markdown
Member Author

@dbirman dbirman Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we don't have a standardized bump template yet https://github.com/AllenNeuralDynamics/.github/tree/main/workflow-templates, maybe that's something we can add to the action items coming out of this group?

Copy link
Copy Markdown
Contributor

@helen-m-lin helen-m-lin Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's here: https://github.com/AllenNeuralDynamics/.github/tree/main/.github/workflows

I think the other folder is legacy?

Copy link
Copy Markdown
Contributor

@Poofjunior Poofjunior Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double-checking that this is now outdated?

Copy link
Copy Markdown
Member Author

@dbirman dbirman Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the correct link, should be visible in the PR now


We use [semver](https://semver.org/) major.minor.patch versions, these are automatically incremented when you use the `aind-library-template`. Note that for major versions you need to put the exact string "BREAKING CHANGE" in the commit *comment* (not the title).
| Prefix | Commit message | Update |
| `<any>:` | | patch |
| `feat:` | | minor |
| `feat!:` or `fix!:` | Include `BREAKING CHANGE` and details | major |

You should set patch version floor `>=1.0.0` and major version ceiling `<2` for each internal dependency that you use. This is good practice for all dependencies.
Unit tests should use [pytest](https://docs.pytest.org/en/stable/). Coverage should be at 100%. Tests should be run before merging pull requests into `main` and `dev`.
Copy link
Copy Markdown

@camilolaiton camilolaiton Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where will we leave the comment of "teams can decide a specific percentage?". In one of the doc files or will this be informal? I prefer this to be written somwhere

Copy link
Copy Markdown
Contributor

@seanmcculloch seanmcculloch Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Handled by Dans addition of:

The decision to deviate from these style standards must be made in consultation with an entire team and be manager-approved. Deviations must be implemented by modifying the pyproject.toml.

on line 18


Team descriptions live in [AIND scientific computing teams](../aind/teams.md).
GitHub automation should use the AIND [reusable workflows](https://github.com/AllenNeuralDynamics/.github/tree/main/.github/workflows).

#### Recommended

- Functions to be annotated with [type hints](https://peps.python.org/pep-0484/).
- Functions should not exceed a complexity of 10 paths (ruff default).
- Functions should [return early](https://medium.com/swlh/return-early-pattern-3d18a41bba8) / [fail fast](https://en.wikipedia.org/wiki/Fail-fast_system).
- Code should be capable of being analyzed by static analysis tools.
- Modules (<1000 lines), classes, and functions (<100 lines) should be manageable size.
- Internal packages should use the naming pattern `<modality>-<process>` wherever possible.
- Packages should not be prefixed with our namespace (i.e. do not put `aind-` as a prefix).
- Internal dependencies should be pinned `==1.0.0` or use *both* a version floor and ceiling `>=1.0.0,<2`.
- Unit tests should cleanup test files or write to temporary folders. Do not version auto-generated code or data in repositories.

### Code Review

[TODO UPDATE]
At least one other software developer needs to approve a pull request in order for it to be merged. Please be courteous when providing feedback. The team lead can resolve any conflicts.

## Resources for SWEs

Expand Down