From 7066a937f5948a809422715458b4833c6aa20600 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 23 Nov 2020 12:48:06 +0100 Subject: [PATCH 1/4] add contributing guidelines to add figures --- CONTRIBUTING.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 378f7aca20..eb1e2aedc3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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) @@ -233,6 +234,29 @@ 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 +specifications, do not hesitate to make a suggestion by showing a draft in a Github issue. + +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 +`src/05-derivatives/images/figure01.png`. + +Figures can be inserted in a Markdown like this: + +```markdown +![ ](relative_path_to_file "alternative name") +``` + +If you are adding a figure (and not picture) make sure to also join a vector format +of that figure (ideally as an `.svg` file). + ## Making a change with a pull request We appreciate all contributions to the BIDS Specification. **THANK YOU** for From 8e5883fc1547205779205525ba9d5b3c3c27dc11 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 27 Nov 2020 12:30:12 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Stefan Appelhoff --- CONTRIBUTING.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb1e2aedc3..3f304bfbd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +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) +- [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) @@ -239,22 +239,24 @@ git commit -m 'STY: Fixed Markdown style' > 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 -specifications, do not hesitate to make a suggestion by showing a draft in a Github issue. +specification, do not hesitate to make a suggestion by showing a draft in a GitHub issue. -You can then submit your image in a pull request. +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 +`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: +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 -![ ](relative_path_to_file "alternative name") +![text to show if image does not load](relative_path_to_file "text to show when hovering over image") ``` -If you are adding a figure (and not picture) make sure to also join a vector format +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). ## Making a change with a pull request From c28b1d34917331eaa0e0018c23944dd77f5789df Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 28 Dec 2020 10:50:08 +0100 Subject: [PATCH 3/4] update recommendations for figure contribution --- CONTRIBUTING.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb1e2aedc3..90265f4c21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -240,7 +240,6 @@ git commit -m 'STY: Fixed Markdown style' If you think that a figure or a picture can help summarize several aspects or notions of the specifications, do not hesitate to make a suggestion by showing a draft in a Github issue. - 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 @@ -254,8 +253,22 @@ Figures can be inserted in a Markdown like this: ![ ](relative_path_to_file "alternative name") ``` -If you are adding a figure (and not picture) make sure to also join a vector format -of that figure (ideally as an `.svg` file). +### Recommendations for figures + +1. Try to keep the file size of your figure relatively small (inferior to 500 Ko) +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 for 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 join 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 From 12586bffd7be2b4ee288ef479c3fac29b50c6089 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Tue, 29 Dec 2020 11:37:49 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Stefan Appelhoff --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cb2f87aae..0191ba0c3d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -257,14 +257,14 @@ Figures can be inserted in a Markdown like this (see also ``` ### Recommendations for figures -1. Try to keep the file size of your figure relatively small (inferior to 500 Ko) +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 for very "comprehensive" +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 join a vector format +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.