[MISC] add contributing guidelines to add figures in the specs

[Remi-Gau]

The need for guidelines regarding figures in the specifications was mentioned in a meeting related to BEP005 and was also pointed in the PET BEP.

This is a PR to get some sort of guidelines started.

Questions

• Do we want to have specific format recommendations for non-vector graphics? png?
• Maybe some size limits on the images too to avoid having people send us 15 Mo images. :-)

I might be overlooking some aspects with the pdf conversion process too that I don't know too well.

[Remi-Gau]

Other questions

Should we mention that the main specs should be for very "comprehensive" figures and that for "smaller" figures they could go in the appendices or the starter kit?

[sappelhoff]

Should we mention that the main specs should be for very "comprehensive" figures and that for "smaller" figures they could go in the appendices or the starter kit?

yes

Just an early comment that I'd like all people who upload an image to include a README file that details where the image came from and how it can be reproduced. Preferably with a link to the file that generated the figure.

Also, I think that several people may advocate for not having image files in this repository at all, and instead including them in a submodule or in some other way. 🤔 so that may be worth thinking about as well. The motivation behind that would be that image files are usually not well tracked with git, and tend to bloat up the history and repo size unnecessarily.

[sappelhoff]

to resolve:

• discuss if it makes more sense to have an "images" repo and include it as a git submodule in bids-specification, rather than adding images here in this repo directly
• add a part to the documentation that users should please add a README (or edit one if already there) that details how their figure was created, preferably with link to the source.

[Remi-Gau]

* discuss if it makes more sense to have an "images" repo and include it as a [git submodule](https://git-scm.com/book/de/v2/Git-Tools-Submodule) in bids-specification, rather than adding images here in this repo directly

I am tempted to kick that one down the road and cross that bridge when we get to it. The reason is that I don't exactly expect the specification to start accumulating images like a "family album".

Another reason is that sub-module adds another layer of technological complexity that could make it harder for people to contribute. ( "A repo within a repo?? I just want to add an image, not shoot a remake of Inception!" 😉 )

So I would suggest clear guidelines on not submitting 15 mb images as a first line of defense.

What do people think?

[sappelhoff]

What do people think?

I agree with that. We don't strictly need the technologically advanced method right now.

[guiomar]

Thanks! I think that figures are always enriching, so would very much like to have illustrations in the specs to facilitate comprehension. I don't know about the technical details. But probably each bep may have max 2 or 3, is this too much? Maybe if in the future, the technical details are difficult to handle, we can explore these repos within repos, but for now we can proceed the simple way, with some indications :)

I also wonder if it could be useful to recommend each bep to have at least one explanatory figure.

[sappelhoff]

I think this is a good addition to our contributor documentation.

PS: The Ci failures are related to the MRI page which is going to be fixed from the PET PR.

[sappelhoff]

Thanks @Remi-Gau