[ENH] BIDS software development guidelines appendix

[yarikoptic]

Related (possibly to be reflected in that doc):

• Add a section articulating the philosophy and make it clear that this is not intended to push any particular set of practices stats-models#54

This PR is primarily to palpate interest and possible objections

Additional TODOs known needed to be done

• verify that linkage to those other documents works (manually until [INFRA] Use linkchecker to verify URLs #79 will come back from the ashes)

[sappelhoff]

Looks like a good thing to have. It reminds me a bit of the BEP LEAD GUIDELINES (formerly Contributor Guide).

Both documents seem to be on the same logical level, so I would propose to either

• make the software development guide a GoogleDoc
• import the BEP LEAD GUIDELINES into github as an appendix

[nicholst]

For the sake of clarity and minimising the nerd factor, I'd remove "driving TCP implementations"

[nicholst]

I don't understand the role of these links... we reference issues inside the spec? Seems fragile.

[sappelhoff]

@franklin-feingold @effigies do yo want to chime in on this PR?

Do you think the contents should be added to the spec? ... or in a different/separate Google Doc?

see also my comment above. @nicholst your comments were more of a concrete nature - but perhaps you also want to voice your opinion on where (and if at all) to include this in general.

[nicholst]

My comments all seem very petty now :)

Anyway, I do see the role and value of guidelines for BIDS software, and it makes sense that it is distinct from BEP LEAD GUIDELINES, right?

E.g., if I'm someone wanting to write software for BIDS 1.0, what does that have to do with a BEP?

So... unless there's another concrete suggestion, here as an appendix seems as good as any place.

[sappelhoff]

Anyway, I do see the role and value of guidelines for BIDS software, and it makes sense that it is distinct from BEP LEAD GUIDELINES, right?

I agree that these should be distinct documents - but I see where the confusion is coming from.

I was simply saying that if we make THESE guidelines (for software) a part of the spec ... then why shouldn't the BEP-Lead-guidelines be a part of the spec as well?

This is just an argument for consistency, and I currently tend towards preferring putting the software guidelines in a google doc (until they grow more substantially) --> instead of importing the BEP-Lead-guidelines also into the appendix (for being consistent).

EDIT: Of course, it's also an option to be inconsistent and have the software guidelines as an appendix, and BEP-lead-guidelines as a Google Doc. But I personally find that confusing.

[franklin-feingold]

My two cents on the point raised in this discussion:

Regarding having this part of the appendix - In the current makeup of the appendix, this document may be better suited to be part of the specification repository (temporarily) rather than in the specification RTD. This would be great in relation to information/repository for contributors (similar to the starter kit, but for contributors. perhaps establishing a need for a contributors repo?). There is infrastructure to be built out to support this type of information effectively (and even overall better establishing the process, documenting, and simplifying the pathway from user to contributor). In the meantime, perhaps this can be part of this repository. It can be in markdown, but if there is dynamic action that arises it can be ported over to google docs and the more rapid commenting/development can happen more seamlessly there. Google doc vs markdown I don't feel strongly either way.

In general, having a set of guidelines to uniformly build out software associated with BIDS will be really important as we move into wrapping up Derivatives, Statistical and Computational Models.

[jasmainak]

It's not clear what this means in the BIDS context

[sappelhoff]

I went ahead and copied the contents to a google doc BIDS Software Development Guidelines

this document may be more easily shared and extended by other contributors.

If it grows and we finally decide what to do with it, we can reopen this PR.

Feel free to challenge this decision.

[yarikoptic]

• "Daddy, daddy!? what is a Google Doc?"
• "Google Doc is where all good but unfinished ideas are moved to let them RiP" ;)