Merge pull request #1562 from sappelhoff/minordoc

DOC: contrib workflow

CONTRIBUTING.md

@@ -709,16 +709,14 @@ BIDS follows the
 [all-contributors](https://github.com/kentcdodds/all-contributors)
 specification, so we welcome and recognize all contributions from documentation
 to testing to code development.
-You can see a list of current contributors in the
-[BIDS specification](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/contributors.md).
-
-If you have made any type of contributions to the BIDS specifications, you can
-either make a change to the
-[contributors document](./src/appendices/contributors.md) and commit as
-part of a pull request or you can edit this
-[page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors)
-of the specification WIKI.
-The WIKI is then synced with the specification with every new release of the specifications.
+You can see a list of contributors in the
+[contributors appendix](https://bids-specification.readthedocs.io/en/stable/appendices/contributors.html)
+of the BIDS specification.
+
+If you have made any type of contributions to BIDS,
+we encourage you to enter or update your information in the
+[Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors)
+according to the instructions listed there.
 
 ## Thank you!
 

DECISION-MAKING.md

@@ -53,11 +53,12 @@ Leaders of BIDS Extension Proposals are listed in the
 
 ### Contributors Group
 
-Contributors are listed in the [Contributors appendix](https://bids-specification.readthedocs.io/en/stable/appendices/contributors.html)
-of the BIDS specification. Contributors who have not yet entered their name
-into this list are encouraged to edit the [Contributors WIKI page](https://github.com/bids-standard/bids-specification/wiki/Contributors)
-with their name, using the emojis listed in the WIKI to indicate their
-contributions.
+Contributors are listed in the
+[Contributors appendix](https://bids-specification.readthedocs.io/en/stable/appendices/contributors.html)
+of the BIDS specification.
+Contributors who have not yet entered their name into this list are encouraged to edit the
+[Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors)
+according to the instructions listed there.
 
 ### Other groups
 

Release_Protocol.md

@@ -75,19 +75,26 @@ It will be generated once the GitHub release has been completed.
 
 #### 2.2 Update the contributors list
 
-Synchronize the [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/contributors.md)
-with the [Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Contributors)
-to ensure all contributors are duly credited.
-Be sure not to remove credits if both have been edited.
+We want to ensure that all contributors are duly credited.
 
+To synchronize the
+[Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/contributors.md)
+with the
+[Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors),
+please follow these steps:
+
+- be sure not to remove credits if both the contributors appendix AND
+  the contributors wiki page have been edited (or the `.tributors` or `.all-contributorsrc` files)
 - add new contributors info to the `tools/new_contributors.tsv` file.
 - make sure that you have installed
   - all the python packages listed in `tools/requirements.txt`
   - the [allcontributors](https://allcontributors.org/docs/en/cli/installation) package
 - run:
+
 ```bash
 make update_contributors
 ```
+
 - you may need to fix some errors in the contributions names in case of crash
 - make sure to review the changes and not commit them blindly
 - commit the changes

tools/add_contributors.py

@@ -1,15 +1,19 @@
-"""Add new contributors listed in new_contributors.tsv to .tributors file
+"""Add new contributors listed in `new_contributors.tsv` to `.tributors` file.
 
-The tributor file is then used to update
-- the CITATION.cff file
-- the .all-contributorsrc file
-- TODO: the table of contributors in the appendix of the spec
+The `.tributors` file is then used to update:
 
-Contrary to the typical .tributors file,
+- the `CITATION.cff` file
+- the `.all-contributorsrc` file
+
+To update the table of contributors in the appendix of the spec,
+run `print_contributors.py`
+
+Contrary to the typical `.tributors` file,
 the one here also centralizes the contributions
-that would otherwise be listed in the .all-contributorsrc file.
+that would otherwise be listed in the `.all-contributorsrc` file.
 
-This can also be used to update all files if new_contributors.tsv is empty.
+This script may also be run to update all files listed above
+if `new_contributors.tsv` is empty.
 """
 
 # TODO: handle the following cases
@@ -39,13 +43,16 @@
 LOG_LEVEL = "DEBUG"  # 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
 
 # Set to True to update the avatars
-# update with your github username and path to a file with github token
+# update with your GitHub username and path to a file with GitHub token
 UPDATE_AVATARS = False
 GH_USERNAME = "Remi-Gau"
 TOKEN_FILE = None
+# if you not want traceback from rich
+# https://rich.readthedocs.io/en/stable/traceback.html
+# set this to False
 RICH_STACKTRACE = False
 
-# Set to True to use some of the dummy data in the "new_contributors.tsv"
+# Set to True to use some of the dummy data in the `new_contributors.tsv`
 TEST = True
 
 
@@ -115,7 +122,7 @@ def emoji_map(reverse=False) -> dict[str, str]:
 def return_this_contributor(
     df: pd.DataFrame, name: str, contribution_needed=True
 ) -> dict[str, Optional[str]]:
-    """Get and validate the data for a given contributor from a panda dataframe"""
+    """Get and validate the data for a given contributor."""
     name = name.strip()
 
     mask = df.name == name
@@ -240,20 +247,20 @@ def update_key(
 
 
 def load_tributors(tributors_file: Path) -> dict:
-    """Load .tributors file."""
+    """Load `.tributors` file."""
     with open(tributors_file, "r", encoding="utf8") as tributors_file:
         return json.load(tributors_file)
 
 
 def write_tributors(tributors_file: Path, tributors: dict[str, dict]) -> None:
-    """Write .tributors file."""
+    """Write `.tributors` file."""
     tributors = sort_tributors(tributors)
     with open(tributors_file, "w", encoding="utf8") as output_file:
         json.dump(tributors, output_file, indent=4, ensure_ascii=False)
 
 
 def return_missing_from_tributors(tributors_file: Path, names: list[str]) -> list[str]:
-    """Return list of names that are in the input file but not in the .tributors file."""
+    """Return list of names present in input file but not in `.tributors` file."""
     tributors = load_tributors(tributors_file)
     tributors_names = [tributors[x]["name"] for x in tributors]
     for i, name in enumerate(names):
@@ -263,7 +270,7 @@ def return_missing_from_tributors(tributors_file: Path, names: list[str]) -> lis
 
 
 def sort_tributors(tributors: dict[str, dict]) -> dict[str, dict]:
-    """Sort tributors alphabetically by name of contributor."""
+    """Sort `.tributors` alphabetically by name of contributor."""
     for key in tributors:
         tributors[key] = dict(OrderedDict(sorted(tributors[key].items())))
     return dict(sorted(tributors.items(), key=lambda item: item[1]["name"]))
@@ -272,7 +279,7 @@ def sort_tributors(tributors: dict[str, dict]) -> dict[str, dict]:
 def add_to_tributors(
     tributors: dict[str, dict], this_contributor: dict[str, str]
 ) -> dict[str, dict]:
-    """Add contributor to .tributors"""
+    """Add contributor to `.tributors`."""
     name = this_contributor.get("name")
 
     tributors_names = [tributors[x]["name"] for x in tributors]
@@ -323,24 +330,24 @@ def update_tributors(
     return tributors
 
 
-"""ALCONTRIB"""
+"""ALLCONTRIB"""
 
 
 def load_allcontrib(allcontrib_file: Path) -> None:
-    """Load .all-contributorsrc file."""
+    """Load `.all-contributorsrc` file."""
     with open(allcontrib_file, "r", encoding="utf8") as input_file:
         return json.load(input_file)
 
 
 def write_allcontrib(allcontrib_file: Path, allcontrib: dict) -> None:
-    """Write .all-contributorsrc file."""
+    """Write `.all-contributorsrc` file."""
     allcontrib = sort_all_contrib(allcontrib)
     with open(allcontrib_file, "w", encoding="utf8") as output_file:
         json.dump(allcontrib, output_file, indent=4, ensure_ascii=False)
 
 
 def sort_all_contrib(allcontrib: dict) -> dict:
-    """Sort .all-contributorsrc file alphabetically by name of contributor."""
+    """Sort `.all-contributorsrc` file alphabetically by name of contributor."""
     for i, contrib in enumerate(allcontrib["contributors"]):
         allcontrib["contributors"][i] = dict(OrderedDict(sorted(contrib.items())))
     allcontrib["contributors"] = sorted(
@@ -350,7 +357,7 @@ def sort_all_contrib(allcontrib: dict) -> dict:
 
 
 def update_allcontrib(allcontrib: dict, this_contributor: dict[str, str]) -> dict:
-    """Add a contributor if not in .all-contributorsrc, or update if already in."""
+    """Add contributor if not already in `.all-contributorsrc`, else update."""
     allcontrib_names = [x["name"] for x in allcontrib["contributors"]]
 
     if this_contributor["name"] not in allcontrib_names:
@@ -379,7 +386,7 @@ def update_allcontrib(allcontrib: dict, this_contributor: dict[str, str]) -> dic
 
 
 def get_gh_avatar(gh_username: str, auth_username: str, auth_token: str) -> str:
-    """Return url of github avatar."""
+    """Return URL of GitHub avatar."""
     avatar_url = None
 
     if gh_username is None:
@@ -413,23 +420,23 @@ def rename_keys_for_allcontrib(this_contributor: dict[str, str]) -> dict[str, st
     return renamed
 
 
-"""CITATION.CFF"""
+"""CITATION.cff"""
 
 
 def load_citation(citation_file: Path) -> dict:
-    """Load CITATION.CFF file."""
+    """Load `CITATION.cff` file."""
     with open(citation_file, "r", encoding="utf8") as input_file:
         return yaml.load(input_file)
 
 
 def write_citation(citation_file: Path, citation: dict) -> None:
-    """Write CITATION.CFF file."""
+    """Write `CITATION.cff` file."""
     with open(citation_file, "w", encoding="utf8") as output_file:
         return yaml.dump(citation, output_file)
 
 
 def return_author_list_for_cff(tributors_file: Path) -> list[dict[str, str]]:
-    """Create an dict to be used for the authors in the CITATION.CFF file."""
+    """Create an dict to be used for the authors in the `CITATION.cff` file."""
     tributors = load_tributors(tributors_file)
 
     author_list = []

tools/print_contributors.py

@@ -1,7 +1,7 @@
-"""Update the table of contributors in the specification appendice.
+"""Update the table of contributors in the specification appendix.
 
 
-Takes the content from ".all-contributorsrc"
+Takes the content from the `.all-contributorsrc` file
 to update the table of contributors names and contribution.
 
 """