[DOC] update to BEP process (#615)

Co-authored-by: Yaroslav Halchenko <[email protected]>
Co-authored-by: christinerogers <[email protected]>

.github/PULL_REQUEST_TEMPLATE/bep.md

@@ -0,0 +1,11 @@
+This is a suggested pull request template for to add BEP to the BIDS website.
+It's designed to capture information we've found to be useful in reviewing pull requests.
+
+If there is other information that would be helpful to include, please don't hesitate to add it!
+
+---
+
+- [ ] indicate the issue in the BIDS specification repository that you opened for your BEP.
+  BIDS specification issue: https://github.com/bids-standard/bids-specification/issues/????
+- [ ] update the `data/beps/beps.yml` document using the template entry described [here](https://github.com/bids-standard/bids-website/tree/main/.github/PULL_REQUEST_TEMPLATE/bep_template.yml)
+- [ ] ensure that BEP leads are listed among BIDS contributors in [the wiki of the BIDS specification](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors#adding-yourself-as-a-contributor)

.github/PULL_REQUEST_TEMPLATE/bep_template.yml

@@ -0,0 +1,29 @@
+---
+-   number:
+    title: # full title
+    display: ' ' # short title for display
+    google_doc: ' '
+    pull_request: ' ' # pull request for the BEP on the BIDS specification repo
+    html_preview: ' ' # link to the html render of the pull request
+                     #  for the BEP on the BIDS specification repo
+    leads:
+  # MUST match given-names and family-names
+  #  from the bids specification citation.cff
+  # Update the list of contributors via the BIDS specification
+  #  if necessary.
+  # See: https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors#adding-yourself-as-a-contributor
+    -   given-names: ' '
+        family-names: ' '
+    bids_maintainers:
+    -   given-names: ' '
+        family-names: ' '
+    status: # updates
+    -   '  ' # add updates
+    -   '  ' # with items
+    blocking: # potential blockers for this BEP
+    -   ' ' # add blocker
+    -   ' ' # with items
+    communication_channel: # mattermost, matrix, slack, discord...
+    google_doc_created: # date when the BEP draft was started: format 'YYYY-MM'
+    pull_request_created: # date when the Proposed BEP was started: format 'YYYY-MM'
+    pull_request_merged: # date when the Proposed BEP was merged: format 'YYYY-MM'

docs/collaboration/governance.md

@@ -280,35 +280,35 @@ OpenStand:
 
 ### B. Standard decision making process overview
 
-The foundation of BIDS decision making is listening to all members of
-the BIDS Community and striving to achieve consensus on each level of
-the BIDS standard process.
+The foundation of BIDS decision making is listening to all members of the BIDS Community
+and striving to achieve consensus on each level of the BIDS standard process.
 
 The criteria for forming a new BEP Working Group:
 
 -   Statement of intent with defined scope, deliverables, and use cases
 -   Statement of intent accepted by the BIDS Steering Group
 
-The criteria of the BIDS Steering Group evaluation for elevating a Draft
-BEP to a Proposed BEP:
+The criteria of the BIDS Steering Group evaluation
+for elevating a Draft BEP to a Proposed BEP:
 
 -   Integrates into the current edition of the standard and is consistent with the BIDS Mission Statement
 -   Clearly defines a filename template and field names
 -   At least 10 business days of community feedback publicly posted across the BIDS channels
 -   Consensus reached among the Working Group
 -   Use cases and examples clearly illustrated
 
-Upon a successful Draft BEP review, the BEP will be converted from a
-Google document to a pull request for the
-[BIDS standard][specification_gh].
-This will enable further community feedback on the Proposed BEP. Tools
-may begin integrating the Proposed BEP specification.
+Upon a successful Draft BEP review,
+the BEP will be converted from a Google document
+to a pull request for the [BIDS standard][specification_gh].
+This will enable further community feedback on the Proposed BEP.
+Tools may begin integrating the Proposed BEP specification.
 
 The criteria for merging a Proposed BEP into the BIDS Standard:
 
 -   Proposal positively reviewed by representative community members.
-    The definition of "representative" will differ depending on the scope of
-    the extension and will be reviewed as part of the steering group's final approval.
+    The definition of "representative" will differ
+    depending on the scope of the extension
+    and will be reviewed as part of the Steering Group's final approval.
 
 -   BIDS Steering Group final approval.
 
@@ -322,47 +322,51 @@ The Steering Group evaluates:
 
 ### A. BEP Procedure: Key definitions
 
-**BIDS Specification** - This is the [BIDS
-specification][specification].
-This covers the current raw data organization for brain MRI, MEG, EEG,
-and iEEG.
+#### BIDS Specification
 
-**BIDS Extension Proposal (BEP)** - A proposal that intends to extend
-BIDS into an unspecified modality or derivative.
+This is the [BIDS specification][specification].
+This covers the current raw data organization for brain MRI, MEG, EEG, and iEEG.
+
+#### BIDS Extension Proposal (BEP)
+
+A proposal that intends to extend BIDS into an unspecified modality or derivative.
 A BEP is typically led by 1-3 individuals with several contributors.
 The [list of BEPs](../extensions/beps.md)
 can be found elsewhere on this website.
 
-**Draft BEP** - The in-progress document, typically in a Google Doc, of
-a BEP. This is dynamic and is grown and maintained at the discretion of
-a BEP Working Group.
+#### Draft BEP
+
+The in-progress document, typically in a Google Doc, of a BEP.
+This is dynamic and is grown and maintained at the discretion of a BEP Working Group.
+
+#### Draft BEP review
+
+This review is performed by the BIDS Steering Group on a Draft BEP.
+The review at this stage aims to ensure the structure clearly defines a template
+and field names along with it integrating into the philosophy, principles, and accepted standards of BIDS.
+The BIDS Steering Group approval action will be a majority vote.
+Upon BIDS Steering Group approval, the Draft BEP will be elevated to a Proposed BEP.
+
+#### Proposed BEP
+
+Once the BIDS Steering Group has approved the Draft BEP,
+it becomes a specific addition and/or modification of BIDS,
+in the form of a Proposed BEP.
+At this time, the Proposed BEP will take the form of a pull request on the [BIDS GitHub repository][specification_gh].
 
-**Draft BEP review** - This review is performed by the BIDS Steering
-Group on a Draft BEP. The review at this stage aims to ensure the
-structure clearly defines a template and field names along with it
-integrating into the philosophy, principles, and accepted standards of
-BIDS. The BIDS Steering Group approval action will be a majority vote.
-Upon BIDS Steering Group approval, the Draft BEP will be elevated to a
-Proposed BEP.
+#### Proposed BEP review
 
-**Proposed BEP** - Once the BIDS Steering Group has approved the Draft
-BEP, it becomes a specific addition and/or modification of BIDS, in the
-form of a Proposed BEP. At this time, the Proposed BEP will take the
-form of a pull request on the [BIDS GitHub
-repository][specification_gh].
+This review is performed by the BIDS Steering Group on the Proposed BEP.
+The review aims to ensure the community input was incorporated
+and the final version integrates into the current edition of the BIDS standard specification.
 
-**Proposed BEP review** - This review is performed by the BIDS Steering
-Group on the Proposed BEP. The review aims to ensure the community input
-was incorporated and the final version integrates into the current
-edition of the BIDS standard specification.
+#### Merged BEP
 
-**Merged BEP** - A Proposed BEP that has been reviewed and approved by
-the Steering Group and merged into the BIDS standard.
+A Proposed BEP that has been reviewed and approved by the Steering Group and merged into the BIDS standard.
 
 ### B. Voting Procedure
 
-The BIDS Steering Group is elected by a vote of the active BIDS Contributors
-Group.
+The BIDS Steering Group is elected by a vote of the active BIDS Contributors Group.
 At the discretion of the BIDS Steering Group,
 additional elections may be called and propositions may be put before
 the community in the course of a Steering Group election.
@@ -415,9 +419,9 @@ of the vote is called into question, then the email addresses will be
 used to hold a special election under the terms laid out in Appendix B,
 according to which,
 
-> Elections will be managed through a 3rd party platform that
-> allows restricting votes to a specific set of email addresses while
-> maintaining the anonymity of the votes.
+Elections will be managed through a 3rd party platform that
+allows restricting votes to a specific set of email addresses while
+maintaining the anonymity of the votes.
 
 ### D. License
 

docs/extensions/beps.md

@@ -11,7 +11,7 @@ Note that all of the extension ideas that are not backwards compatible and thus
 
 {{ MACROS___generate_beps_table(file="beps.yml") }}
 
-## Completed BEPs
+## Merged BEPs
 
 When an extension reaches maturity it is merged into the main body of the specification.
 Below is a table of BEPs that have been merged.