From 2ec34f4ea61ddcc97b5cf8860d44b7a5321d5490 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Mon, 24 Jul 2023 10:54:36 +0200 Subject: [PATCH 1/3] DOC: contrib workflow --- CONTRIBUTING.md | 18 +++++------- DECISION-MAKING.md | 11 +++---- Release_Protocol.md | 15 +++++++--- tools/add_contributors.py | 58 ++++++++++++++++++++----------------- tools/print_contributors.py | 4 +-- 5 files changed, 58 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40fae2e3ea..6062287227 100644 --- a/CONTRIBUTING.md +++ b/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/Contributors) +according to the instructions listed there. ## Thank you! diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 05e4c91887..96d1014a97 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -52,11 +52,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/Contributors) +according to the instructions listed there. ### Other groups diff --git a/Release_Protocol.md b/Release_Protocol.md index 5773da78e3..4bbae02978 100644 --- a/Release_Protocol.md +++ b/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/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 diff --git a/tools/add_contributors.py b/tools/add_contributors.py index 8c3891d26e..8cee879b62 100644 --- a/tools/add_contributors.py +++ b/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,13 @@ 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 -RICH_STACKTRACE = False +RICH_STACKTRACE = False # XXX: what is this? -# 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 @@ -114,7 +118,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 @@ -239,20 +243,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): @@ -262,7 +266,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"])) @@ -271,7 +275,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] @@ -322,24 +326,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( @@ -349,7 +353,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: @@ -378,7 +382,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: @@ -412,23 +416,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 = [] diff --git a/tools/print_contributors.py b/tools/print_contributors.py index 62f5c7cf92..c49ca6f823 100644 --- a/tools/print_contributors.py +++ b/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. """ From 9d4559bc5e8ddb4a17720befcf6d97dffc0146aa Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Thu, 24 Aug 2023 22:50:18 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Stefan Appelhoff --- CONTRIBUTING.md | 2 +- DECISION-MAKING.md | 2 +- Release_Protocol.md | 2 +- tools/add_contributors.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6062287227..27f56db383 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -715,7 +715,7 @@ 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/Contributors) +[Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors) according to the instructions listed there. ## Thank you! diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 13153f2824..a29b4b8632 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -57,7 +57,7 @@ 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) +[Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors) according to the instructions listed there. ### Other groups diff --git a/Release_Protocol.md b/Release_Protocol.md index 4bbae02978..1950d36a26 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -80,7 +80,7 @@ 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/Contributors), +[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 diff --git a/tools/add_contributors.py b/tools/add_contributors.py index 8cee879b62..fe7c562b87 100644 --- a/tools/add_contributors.py +++ b/tools/add_contributors.py @@ -326,7 +326,7 @@ def update_tributors( return tributors -"""ALlCONTRIB""" +"""ALLCONTRIB""" def load_allcontrib(allcontrib_file: Path) -> None: From e73e0bc11f07c80d877c82099180048f6b99dee5 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Thu, 24 Aug 2023 22:53:51 +0200 Subject: [PATCH 3/3] Apply suggestions from code review --- tools/add_contributors.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/add_contributors.py b/tools/add_contributors.py index fe7c562b87..4c5967edac 100644 --- a/tools/add_contributors.py +++ b/tools/add_contributors.py @@ -47,7 +47,10 @@ UPDATE_AVATARS = False GH_USERNAME = "Remi-Gau" TOKEN_FILE = None -RICH_STACKTRACE = False # XXX: what is this? +# 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` TEST = True