From f1b6f2a9e325d7369e3327e393c516bea19edb60 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Tue, 6 Feb 2024 17:03:42 +0100 Subject: [PATCH 1/6] improve guidelines --- docs/guide.md | 54 +++++++++++++++++++++++++++++++-------------------- mkdocs.yml | 2 +- 2 files changed, 34 insertions(+), 22 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index f6a681e..2fc263b 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -40,15 +40,18 @@ If something being added to BIDS is applicable to at least 80% of use cases ## When and how to start a BIDS Extension Proposal? -Small contributions (typos, rephrasing of a description, adding a single new - metadata field) can be just added as a - [Pull Request on GitHub](https://github.com/bids-standard/bids-specification/pulls) +!!! warning "Does this change need to be a BEP?" -Larger contributions that are expected to involve longer and more involved - discussions should be first described in a standalone document: a Google Docs - BEP. Development on Google Docs is preferred as this is a low barrier to entry - for colleagues who do not use GitHub and/or Markdown, - allowing more people to get involved. + Small contributions + (typos, rephrasing of a description, adding a single new metadata field) + can be just added to the BIDS specification + as a [Pull Request on GitHub](https://github.com/bids-standard/bids-specification/pulls) + +Larger contributions that are expected to involve longer and more involved discussions +should be first described in a standalone document: a Google Docs BEP. +Development on Google Docs is preferred as this is a low barrier to entry +for colleagues who do not use GitHub and/or Markdown, +allowing more people to get involved. 1. Explore [the specification](bids-specification.readthedocs.io) and [the BEP lists](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification) @@ -56,16 +59,15 @@ Larger contributions that are expected to involve longer and more involved that may support what you are trying to add into the BIDS Specification. Someone may have already done work for you. -2. Read the - [BIDS governance document](https://bids.neuroimaging.io/governance.html). +1. Read the [BIDS governance document](https://bids.neuroimaging.io/governance.html). -3. Familiarize yourself with the BIDS community by browsing current issues, +1. Familiarize yourself with the BIDS community by browsing current issues, discussions, and proposed changes on [the BIDS specification repository]. Search for issues relating to your feature or BEP idea before creating a new issue. -4. Open an initial “issue” on +1. Open an initial “issue” on [the BIDS specification repository] issues page to gauge interest in your potential BEP, and to collect feedback by more community members and @@ -73,8 +75,8 @@ Larger contributions that are expected to involve longer and more involved **This is an important step before proceeding in order to make sure that more consensus arises and more contributors are aware what is happening**. -5. Communicate with the BIDS maintainers to make your BEP official. This - entails registering the BEP with a number on +1. Communicate with the BIDS maintainers to make your BEP official. + This entails registering the BEP with a number on [the BIDS website](https://bids.neuroimaging.io/get_involved.html). To obtain a number for your BEP, follow the previous steps and then [open a new issue](https://github.com/bids-standard/bids-website/issues) @@ -82,32 +84,42 @@ Larger contributions that are expected to involve longer and more involved [website GitHub repository](https://github.com/bids-standard/bids-website/), cross-linking to any other already existing issues. -6. Create a draft of your extension by discussing among colleagues. The +## Developping the BIDS extension proposal + +1. Create a draft of your extension by discussing among colleagues. The [BIDS Extension Proposal template](https://docs.google.com/document/d/1W7--Mf3gCCb1mVfhsoRJCAKFhmf2umG1PFkyZ1jEgMw/edit#) provides some boilerplate and formatting conventions. -7. List on the draft the contributor(s) leading the effort. +1. List on the draft the contributor(s) leading the effort. -8. Share the draft (remember to +1. Share the draft (remember to [share a link that allows anyone to comment](https://support.google.com/docs/answer/2494822?co=GENIE.Platform%3DDesktop&hl=en)) with the [bids-discussion mailing list](https://groups.google.com/forum/#!forum/bids-discussion) and ask for comments. -9. Incorporate the feedback and strive for consensus. +1. Incorporate the feedback and strive for consensus. -10. Help to merge the extension into the main specification (this will require +1. Help to merge the extension into the main specification (this will require converting the proposal to Markdown and submitting a Pull Request at [the BIDS specification repository]) -11. Create example datasets. +1. Create example datasets. + + !!! Note + In some cases, examples for the BEP can be designed earlier in the BEP process. + This can help make things more concrete and make it more obvious + what aspects of the BEP work and what aspect may need to be reworked. -12. If necessary, contribute a pull request to the +1. If necessary, contribute a pull request to the [BIDS Validator repository](https://github.com/bids-standard/bids-validator) as well to incorporate the extension. ![bep_process](assets/img/bep_process.png) + + + ## Advice for extending BIDS ### Limit flexibility, consider tool developers diff --git a/mkdocs.yml b/mkdocs.yml index 1fc87f7..a99f08e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,4 +53,4 @@ markdown_extensions: anchorlink: true - pymdownx.superfences - pymdownx.details - - admonition + - admonition \ No newline at end of file From 21b5d96f42c7fe1a229c1611eef5ad25b2394018 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 19 Feb 2024 10:37:56 +0100 Subject: [PATCH 2/6] reorder steps --- docs/guide.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index 2fc263b..cd9008b 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -53,27 +53,24 @@ Development on Google Docs is preferred as this is a low barrier to entry for colleagues who do not use GitHub and/or Markdown, allowing more people to get involved. -1. Explore [the specification](bids-specification.readthedocs.io) - and [the BEP lists](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification) - to find existing or ongoing efforts - that may support what you are trying to add into the BIDS Specification. +1. Check [the lists of opened BEPs](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification) + to find existing or ongoing efforts that may overlap with your idea. Someone may have already done work for you. -1. Read the [BIDS governance document](https://bids.neuroimaging.io/governance.html). - -1. Familiarize yourself with the BIDS community by browsing current issues, - discussions, and proposed changes on - [the BIDS specification repository]. +1. Check the [opened issues about BEPs](https://github.com/bids-standard/bids-specification/issues?q=is%3Aissue+is%3Aopen+label%3ABEP), Search for issues relating to your feature or BEP idea before creating a new issue. 1. Open an initial “issue” on - [the BIDS specification repository] issues page + the BIDS specification repository [issues page] to gauge interest in your potential BEP, and to collect feedback by more community members and [BIDS maintainers](https://github.com/bids-standard/bids-specification/blob/master/DECISION-MAKING.md#maintainers-group). - **This is an important step before proceeding in order to make sure that - more consensus arises and more contributors are aware what is happening**. + +!!! warning + + This is an important step before proceeding in order to make sure that + more consensus arises and more contributors are aware what is happening. 1. Communicate with the BIDS maintainers to make your BEP official. This entails registering the BEP with a number on @@ -84,6 +81,14 @@ allowing more people to get involved. [website GitHub repository](https://github.com/bids-standard/bids-website/), cross-linking to any other already existing issues. + + + + ## Developping the BIDS extension proposal 1. Create a draft of your extension by discussing among colleagues. The From d9d26ea8a8fe751ba7aeec697f24ab7c03f2abc8 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 19 Feb 2024 10:49:12 +0100 Subject: [PATCH 3/6] link to examples --- docs/guide.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index cd9008b..6f08afd 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -81,16 +81,14 @@ allowing more people to get involved. [website GitHub repository](https://github.com/bids-standard/bids-website/), cross-linking to any other already existing issues. - ## Developping the BIDS extension proposal +1. Make sure you are familiar with [the BIDS specification]https://bids-specification.readthedocs.io/en/latest/) + and the [bids-examples](https://github.com/bids-standard/bids-examples). + 1. Create a draft of your extension by discussing among colleagues. The [BIDS Extension Proposal template](https://docs.google.com/document/d/1W7--Mf3gCCb1mVfhsoRJCAKFhmf2umG1PFkyZ1jEgMw/edit#) provides some boilerplate and formatting conventions. @@ -109,7 +107,7 @@ allowing more people to get involved. converting the proposal to Markdown and submitting a Pull Request at [the BIDS specification repository]) -1. Create example datasets. +1. Create example datasets to add to the [bids-examples](https://github.com/bids-standard/bids-examples). !!! Note In some cases, examples for the BEP can be designed earlier in the BEP process. From c02a16a1a83a7742bba1d67b72ad2e02ca1b4f01 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Mon, 19 Feb 2024 11:03:05 +0100 Subject: [PATCH 4/6] list of steps to develop BEP --- docs/guide.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index 6f08afd..4377306 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -86,14 +86,17 @@ allowing more people to get involved. ## Developping the BIDS extension proposal -1. Make sure you are familiar with [the BIDS specification]https://bids-specification.readthedocs.io/en/latest/) +1. Make sure you are familiar with [the BIDS specification](https://bids-specification.readthedocs.io/en/latest/) and the [bids-examples](https://github.com/bids-standard/bids-examples). -1. Create a draft of your extension by discussing among colleagues. The - [BIDS Extension Proposal template](https://docs.google.com/document/d/1W7--Mf3gCCb1mVfhsoRJCAKFhmf2umG1PFkyZ1jEgMw/edit#) +1. Create a draft of your extension by discussing among colleagues + along with minimal dataset examples. + The [BIDS Extension Proposal template](https://docs.google.com/document/d/1W7--Mf3gCCb1mVfhsoRJCAKFhmf2umG1PFkyZ1jEgMw/edit#) provides some boilerplate and formatting conventions. -1. List on the draft the contributor(s) leading the effort. + !!! Note + Designing aexamples early in the BEP process can help make things more concrete + and make it more obvious what aspects of the BEP work and what aspect may need to be reworked. 1. Share the draft (remember to [share a link that allows anyone to comment](https://support.google.com/docs/answer/2494822?co=GENIE.Platform%3DDesktop&hl=en)) @@ -107,13 +110,6 @@ allowing more people to get involved. converting the proposal to Markdown and submitting a Pull Request at [the BIDS specification repository]) -1. Create example datasets to add to the [bids-examples](https://github.com/bids-standard/bids-examples). - - !!! Note - In some cases, examples for the BEP can be designed earlier in the BEP process. - This can help make things more concrete and make it more obvious - what aspects of the BEP work and what aspect may need to be reworked. - 1. If necessary, contribute a pull request to the [BIDS Validator repository](https://github.com/bids-standard/bids-validator) as well to incorporate the extension. From f092c4d7cb12cc82421f5b737fbe9899db1aa3db Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 28 Feb 2024 10:29:00 +0000 Subject: [PATCH 5/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index 660f572..99916d1 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -66,7 +66,7 @@ allowing more people to get involved. to gauge interest in your potential BEP, and to collect feedback by more community members and [BIDS maintainers](https://github.com/bids-standard/bids-specification/blob/master/DECISION-MAKING.md#maintainers-group). - + !!! warning This is an important step before proceeding in order to make sure that @@ -89,12 +89,12 @@ allowing more people to get involved. 1. Make sure you are familiar with [the BIDS specification](https://bids-specification.readthedocs.io/en/latest/) and the [bids-examples](https://github.com/bids-standard/bids-examples). -1. Create a draft of your extension by discussing among colleagues +1. Create a draft of your extension by discussing among colleagues along with minimal dataset examples. The [BIDS Extension Proposal template](https://docs.google.com/document/d/1W7--Mf3gCCb1mVfhsoRJCAKFhmf2umG1PFkyZ1jEgMw/edit#) provides some boilerplate and formatting conventions. - !!! Note + !!! Note Designing aexamples early in the BEP process can help make things more concrete and make it more obvious what aspects of the BEP work and what aspect may need to be reworked. From 02bca7301f386d11b03cac32e08d8553d857e22a Mon Sep 17 00:00:00 2001 From: Yaroslav Halchenko Date: Thu, 21 Mar 2024 09:40:15 -0400 Subject: [PATCH 6/6] Two minor typo fixes --- docs/guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index 99916d1..ea8e485 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -84,7 +84,7 @@ allowing more people to get involved. -## Developping the BIDS extension proposal +## Developing the BIDS extension proposal 1. Make sure you are familiar with [the BIDS specification](https://bids-specification.readthedocs.io/en/latest/) and the [bids-examples](https://github.com/bids-standard/bids-examples). @@ -95,7 +95,7 @@ allowing more people to get involved. provides some boilerplate and formatting conventions. !!! Note - Designing aexamples early in the BEP process can help make things more concrete + Designing examples early in the BEP process can help make things more concrete and make it more obvious what aspects of the BEP work and what aspect may need to be reworked. 1. Share the draft (remember to