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 1 commit
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
47 changes: 38 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,52 @@

## 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 | ... |

Individual projects that deviate from these standards **must do so by modifying the pyproject.toml**.

#### Standard

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.
Package management should be handled by [uv](https://docs.astral.sh/uv/).

### Versioning
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, or more.
Comment thread
dbirman marked this conversation as resolved.
Outdated

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).
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


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.
| Prefix | Update |
| `<any>:` | patch |
| `feat:` | minor |
| `BREAKING CHANGE` | major |

Team descriptions live in [AIND scientific computing teams](../aind/teams.md).
Unit tests should use [pytest](https://docs.pytest.org/en/stable/). Coverage should be at 100%. The decision to lower test coverage below 100% must be made in consultation with an entire team and be manager-approved. Tests should be run before merging pull requests into `main` and `dev`.

#### 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 use *both* a version floor and ceiling `>=1.0.0,<2`.
Comment thread
dbirman marked this conversation as resolved.
Outdated
- 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