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.

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

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

Merged
merged 5 commits into from
Jan 6, 2021
Merged
Changes from all commits
Commits
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
39 changes: 39 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ Jump to the following sections:
- [Understanding issues](#understanding-issues)
- [Writing in markdown](#writing-in-markdown)
- [Fixing Remark errors from Travis](#fixing-travis-remark-errors)
- [Adding a figure to the specifications](#adding-a-figure-to-the-specifications)
- [Making a change with a pull request](#making-a-change-with-a-pull-request)
- [Example pull request](#example-pull-request)
- [Commenting on a pull request](#commenting-on-a-pull-request)
Expand Down Expand Up @@ -233,6 +234,44 @@ git add flagged_file.md
git commit -m 'STY: Fixed Markdown style'
```

## Adding a figure to the specifications

> A figure is worth a 1000 words!

If you think that a figure or a picture can help summarize several aspects or notions of the
specification, do not hesitate to make a suggestion by showing a draft in a GitHub issue.

After discussion and approval by the community, you can then submit your image
in a pull request.

Images should be added to an `images` folder that is at the same level as the Markdown file
where your image will be added. For example if you want to add a figure `figure01.png` to
`src/05-derivatives/01-introduction.md` then your image should go to
`src/05-derivatives/images/figure01.png`.

Figures can be inserted in a Markdown like this (see also
[Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#images)):

```markdown
![text to show if image does not load](relative_path_to_file "text to show when hovering over image")
```
### Recommendations for figures

1. Try to keep the file size of your figure relatively small (smaller than 500 Kb)
to keep the repository light and reduce the load time of the specs
for people who do not necessarily have broad-band internet.

1. Figures in the main part of the specification should aim to be very "comprehensive"
but "smaller" figures can find their home in the appendices or the BIDS-starter-kit.

1. If you are adding a figure (and not picture) make sure to also supply a vector format
of that figure (ideally as an `.svg` file) as this makes it easier to edit it in the
future.

1. Try to include a README file that details where the figure / image came from
and how it can be reproduced. Preferably with a link to the file that generated the figure
if relevant.

## Making a change with a pull request

We appreciate all contributions to the BIDS Specification. **THANK YOU** for
Expand Down