From ef41d98e112b9917e025ddd0abd2db22ee66a0f0 Mon Sep 17 00:00:00 2001 From: Arielle Leon Date: Mon, 16 Feb 2026 13:38:38 -0800 Subject: [PATCH 1/5] fix: add examples to major, minor and patch changes --- docs/source/process_data/version_pipelines.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/source/process_data/version_pipelines.md b/docs/source/process_data/version_pipelines.md index 5b207d9..c3e0792 100644 --- a/docs/source/process_data/version_pipelines.md +++ b/docs/source/process_data/version_pipelines.md @@ -6,8 +6,19 @@ Users need to understand how to interact with computed results produced by data Core data processing pipelines MUST adopt [semantic versioning](https://semver.org/). - Major version changes indicate that the structure or interpretation of the data has changed. + + - Update to `aind-data-schema` that renames or restructures the metadata. + - Any default parameter changes. + - Changes to the output file structure. + - Minor version changes indicate new, backwards compatible features were added to the pipeline. -- Patch version changes indicate bug fixes. + + - Add a new parameter to the input arguments. + - Add a new QC plot. + +- Patch version changes indicate backwards compatible bug fixes. + + - Critical bug fixes that do not alter the data structure. The pipeline's name and semantic version MUST be stored in aind-data-schema [Processing](https://github.com/AllenNeuralDynamics/aind-data-schema/blob/dev/src/aind_data_schema/core/processing.py#L970) metadata at the top level of the results. @@ -52,4 +63,4 @@ When querying the metadata database for `Processing.pipeline_version`, users and - Semantic versions `< 0.2.0` (i.e., `0.1.0`, `0.1.1`) - Code Ocean versions from before semantic versioning was adopted (i.e., `18.0`) -For pipelines that have adopted semantic versioning, users and developers will always be able to find a pipelines semantic version in the `nextflow.config`. \ No newline at end of file +For pipelines that have adopted semantic versioning, users and developers will always be able to find a pipelines semantic version in the `nextflow.config`. From 025214bc3dae62c6ce487c661e4b363cb1220e0e Mon Sep 17 00:00:00 2001 From: Arielle Leon Date: Mon, 16 Feb 2026 15:52:58 -0800 Subject: [PATCH 2/5] fix: add clarity to major version change example --- docs/source/process_data/version_pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/process_data/version_pipelines.md b/docs/source/process_data/version_pipelines.md index c3e0792..b33f3c9 100644 --- a/docs/source/process_data/version_pipelines.md +++ b/docs/source/process_data/version_pipelines.md @@ -9,7 +9,7 @@ Core data processing pipelines MUST adopt [semantic versioning](https://semver.o - Update to `aind-data-schema` that renames or restructures the metadata. - Any default parameter changes. - - Changes to the output file structure. + - Changes to the output file structure, even if fixing previously incorrect behavior. - Minor version changes indicate new, backwards compatible features were added to the pipeline. From 81309e5bc3a1848b81704f248b3f79c608e3bed9 Mon Sep 17 00:00:00 2001 From: Arielle Leon Date: Wed, 25 Feb 2026 09:57:03 -0800 Subject: [PATCH 3/5] docs: add new section to better describe major/minor/patch updates --- docs/source/process_data/version_pipelines.md | 35 +++++++++++-------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/source/process_data/version_pipelines.md b/docs/source/process_data/version_pipelines.md index b33f3c9..d7370b8 100644 --- a/docs/source/process_data/version_pipelines.md +++ b/docs/source/process_data/version_pipelines.md @@ -4,21 +4,8 @@ Users need to understand how to interact with computed results produced by data ## Policies -Core data processing pipelines MUST adopt [semantic versioning](https://semver.org/). -- Major version changes indicate that the structure or interpretation of the data has changed. +Core data processing pipelines MUST adopt [semantic versioning](https://semver.org/). See Ver - - Update to `aind-data-schema` that renames or restructures the metadata. - - Any default parameter changes. - - Changes to the output file structure, even if fixing previously incorrect behavior. - -- Minor version changes indicate new, backwards compatible features were added to the pipeline. - - - Add a new parameter to the input arguments. - - Add a new QC plot. - -- Patch version changes indicate backwards compatible bug fixes. - - - Critical bug fixes that do not alter the data structure. The pipeline's name and semantic version MUST be stored in aind-data-schema [Processing](https://github.com/AllenNeuralDynamics/aind-data-schema/blob/dev/src/aind_data_schema/core/processing.py#L970) metadata at the top level of the results. @@ -64,3 +51,23 @@ When querying the metadata database for `Processing.pipeline_version`, users and - Code Ocean versions from before semantic versioning was adopted (i.e., `18.0`) For pipelines that have adopted semantic versioning, users and developers will always be able to find a pipelines semantic version in the `nextflow.config`. + +## Major/minor/patch + +Standard semantic versioning alone does not fully capture the needs of data processing pipelines. In particular, conventional commit types such as `fix`, `refactor`, and `feat` can each be either breaking or non-breaking, and breaking changes can differ in kind: some change output content (a downstream process may produce wrong results), while others change output structure or processing fundamentals (a downstream process fails entirely). + +The table below maps conventional commit types to the appropriate version bump: + +| Commit type | Description | Version bump | +|---|---|---| +| `build` | Changes to build system or external dependencies (larger than a dependency bugfix patch) | minor | +| `feat` | A new feature added to output without changing existing output | minor | +| `refactor` | A code change that neither fixes a bug nor adds a feature | minor | +| `perf` | A code change that improves performance with output unchanged | minor | +| `fix` | A bug fix that resolves failures only | patch | +| `ci` | Changes to CI configuration files and scripts | patch | +| `docs` | Documentation only changes | patch | +| `style` | Changes that do not affect the meaning of the code (white-space, formatting, etc.) | patch | +| `test` | Adding missing tests or correcting existing tests | patch | +| `feat[breaking]` or `refactor[breaking]` | Fundamentally changes the processing approach or output structure such that results before and after are not directly comparable | major | +| `fix[breaking]` | A bug fix that resolves erroneous output (changing previously incorrect results) | minor — proactively reprocess affected data and highlight in changelog | From 2514d405484c78ca018e48e24c016994f09d12ce Mon Sep 17 00:00:00 2001 From: Arielle Leon Date: Wed, 25 Feb 2026 09:58:28 -0800 Subject: [PATCH 4/5] fix: link to versioning section --- docs/source/process_data/version_pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/process_data/version_pipelines.md b/docs/source/process_data/version_pipelines.md index d7370b8..5f84af4 100644 --- a/docs/source/process_data/version_pipelines.md +++ b/docs/source/process_data/version_pipelines.md @@ -4,7 +4,7 @@ Users need to understand how to interact with computed results produced by data ## Policies -Core data processing pipelines MUST adopt [semantic versioning](https://semver.org/). See Ver +Core data processing pipelines MUST adopt [semantic versioning](https://semver.org/). See [Major/minor/patch](#majorminorpatch) section below The pipeline's name and semantic version MUST be stored in aind-data-schema [Processing](https://github.com/AllenNeuralDynamics/aind-data-schema/blob/dev/src/aind_data_schema/core/processing.py#L970) metadata at the top level of the results. From b1be0db7f3af6a8526553374b85bfbdb8a9f24d3 Mon Sep 17 00:00:00 2001 From: Arielle Leon Date: Thu, 19 Mar 2026 10:09:04 -0700 Subject: [PATCH 5/5] fix: finalize commit type, descriptions and version --- docs/source/process_data/version_pipelines.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/source/process_data/version_pipelines.md b/docs/source/process_data/version_pipelines.md index 5f84af4..1c91be2 100644 --- a/docs/source/process_data/version_pipelines.md +++ b/docs/source/process_data/version_pipelines.md @@ -60,7 +60,7 @@ The table below maps conventional commit types to the appropriate version bump: | Commit type | Description | Version bump | |---|---|---| -| `build` | Changes to build system or external dependencies (larger than a dependency bugfix patch) | minor | +| `build` | Changes to build system or external dependencies | minor | | `feat` | A new feature added to output without changing existing output | minor | | `refactor` | A code change that neither fixes a bug nor adds a feature | minor | | `perf` | A code change that improves performance with output unchanged | minor | @@ -69,5 +69,7 @@ The table below maps conventional commit types to the appropriate version bump: | `docs` | Documentation only changes | patch | | `style` | Changes that do not affect the meaning of the code (white-space, formatting, etc.) | patch | | `test` | Adding missing tests or correcting existing tests | patch | -| `feat[breaking]` or `refactor[breaking]` | Fundamentally changes the processing approach or output structure such that results before and after are not directly comparable | major | -| `fix[breaking]` | A bug fix that resolves erroneous output (changing previously incorrect results) | minor — proactively reprocess affected data and highlight in changelog | +| `fix!` | Breaking change to something in the code | minor | +| `feat!` | Breaking change and will change how it's highlighted in the changelog | minor| +| `BREAKING` (footer) | Fundamental changes the processing approach or output structure such that results before and after are not directly comparable | major | +