Skip to content
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

[ENH] adding release guidelines #267

Merged
merged 6 commits into from
Jul 25, 2019
Merged

[ENH] adding release guidelines #267

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a13c2ab
Merge pull request #19 from bids-standard/master
franklin-feingold Jul 11, 2019
8047a9c
Added release guideline md
franklin-feingold Jul 11, 2019
4c6f8c9
Apply suggestions from code review
franklin-feingold Jul 11, 2019
aede41d
Apply suggestions from code review
franklin-feingold Jul 16, 2019
ca6a86c
Apply suggestions from code review
franklin-feingold Jul 18, 2019
a1d06c4
Apply suggestions from code review
franklin-feingold Jul 25, 2019
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
40 changes: 40 additions & 0 deletions Release_Guideline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Release Guidelines

This document captures guidelines to follow when considering a new release of the BIDS specification.
franklin-feingold marked this conversation as resolved.
Show resolved Hide resolved

franklin-feingold marked this conversation as resolved.
Show resolved Hide resolved
## Background
BIDS has generally followed a semantic versioning (semver) approach.
The canonical semver text can be found at https://semver.org/, and an adaptation to documents can be found at https://semverdoc.org/.
A specification falls somewhere between these two, as documentation does not require
backwards compatibility, while software has notions of bugs and features which do not
map to the reasons for updating a specification.

In both cases, edition numbers are specified as MAJOR.MINOR.PATCH, and the difference is in the rules for incrementing each edition number.

In BIDS, we have considered a major release version (the next being 2.0.0) to indicate
backwards-incompatible changes, while minor and patch releases must be backwards compatible.
franklin-feingold marked this conversation as resolved.
Show resolved Hide resolved

## Guidelines

franklin-feingold marked this conversation as resolved.
Show resolved Hide resolved
Once a decision for a release has been established, the rules of [decision-making](DECISION-MAKING.md)
govern the mechanism of doing the release, *i.e.*, waiting 5 business days and obtaining
the approval of at least one maintainer before merging.

### Minor (1.X.0) releases

A minor release should be made when a BEP (BIDS Extension Proposal) has been merged into the
specification.
The BIDS Maintainers have discretion to identify other cases justifying a minor release.

### Patch (1.X.Y) releases

Patch releases will generally be more frequent, and indicate less significant changes to the specification.
The following is a non-exhaustive set of justifications for a patch release:

- A modality field has changed and the [bids-validator](https://github.com/bids-standard/bids-validator) has been updated to reflect this change.
- Links or information in the specification are no longer accurate, *e.g.* if a BEP document is added or moved
- The rendering of the [specification](https://bids-specification.readthedocs.io/en/stable/) has changed
- A metadata field or file type is added at the request of a curator attempting to release BIDS-compliant data

Ultimately, all releases are a matter of maintainer discretion, but patch release frequency should
balance community needs for stability and responsiveness.