Release guidelines

[franklin-feingold]

Hi BIDS Community!

I noticed that we do not have a document outlining release guidelines. This would be good to document and make clear for when a release is ready to be processed. I have started a google document to capture these guidelines. Love to get thoughts/feedback on it!

We are likely due for a release soon, but good to document this decision-making process to make it more clear

Thank you!

[sappelhoff]

Thanks for raising this @franklin-feingold - I agree that we should do a minor patch release soon, mainly to move all infrastructural changes of the Mkdocs setup from latest to stable and hence make these improvements visible. (clickable links, logos, panel to dynamically select versions, typo and link fixes, ... and numerous other improvements)

PS: I am talking about incrementing the third number in X.X.X

[sappelhoff]

tagging a related issue (we want our release to have dates): #199

[emdupre]

+1 on these guidelines. Thanks, @franklin-feingold ! Can we also make it clear how the decision to release relates to our decision-making document ? Since they're likely to interact !

[franklin-feingold]

Regarding release dates - we have this documented in the Release_Protocol step 6

I agree they are likely to interact, but the decision-making kicks in once the decision to release has been established. The rules of decision-making govern the mechanism of doing the release (i.e. waiting 5 business days to merge), but the guidelines are meant to give structure on when to release. Perhaps providing this distinction in the document may help give clarity? I can add this section in. wdyt?

edit: to note - I am thinking of converting the google document to markdown in the middle of next week and opening a PR. Please raise if there are potential blockers that should be resolved before the conversion and PR opening (I do not see any other than the release guideline to decision-making interaction). Thank you!

[emdupre]

That would be helpful, I think ! Though I have one more question :

the decision-making kicks in once the decision to release has been established. The rules of decision-making govern the mechanism of doing the release (i.e. waiting 5 business days to merge), but the guidelines are meant to give structure on when to release

I think my confusion here comes in mostly for the patch releases, since the guidelines recognize that there's some ambiguity about when smaller changes will add up to a release. Maybe we could specify that it's a judgement call that falls to a maintainer?

[effigies]

Maybe we could specify that it's a judgement call that falls to a maintainer?

👍

there's some ambiguity about when smaller changes will add up to a release.

As the start of a guideline, additions that seem to be motivated by a use case should probably trigger a timer, formally or informally. If somebody needs to augment the spec in order to make their data conformant, provide a name for metadata required by their app, or refine the semantics of pybids or some other parser, then I think we have some obligation to release relatively promptly (<2 months).

Should probably write this suggestion into the doc, but just to throw it out here while I'm thinking of it.

[franklin-feingold]

Both sound good to me!

I have added some text in the release guideline to address when the decision making rules come into effect and what they govern. Also that the judgment for a patch release falls onto the maintainer working group with a 'motivated by use case' example added to the list of actions that can trigger the patch release decision.

I like the idea of giving a timer to the next release. This timer can be set on the readme file and on the website to indicate a release is close to being made.

[sappelhoff]

closed by #267