From fab3381318718fb5feceed0f2997a1830a0548e4 Mon Sep 17 00:00:00 2001 From: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> Date: Wed, 28 Jan 2026 13:17:36 -0500 Subject: [PATCH 1/3] Clarify license and citation guidance for Hugging Face Pull from Collab Guide [PR 51](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/51) * Clarify license section, include link to policy clear up confusion over need for file or use of MIT license for datasets * Remove 'Imageomics' in front of policy, no need for that specification here * Add pro-tip to use data/model card checklists * Clarify license recommendations/references in templates aligns with repo guide page clarification * Add citation clarification in note under standard files * Add choose-a-license link back in still a good reference for both datasets and models * Clarify license not supported, as it's more about how the system works include also the links to the repo card templates * fix: correct broken link and abbreviation in dataset card template Remove extra opening parenthesis in the Digital Products Release and Licensing Policy link that broke the markdown rendering. Also fix "eg." to "e.g." on the same line for correctness. --------- Co-authored-by: Graham Taylor --- .../wiki-guide/HF_DatasetCard_Template_ABC.md | 5 ++--- .../HF_DatasetCard_Template_mkdocs.md | 3 +++ .../HF_ModelCard_Template_mkdocs.md | 3 +++ docs/wiki-guide/Hugging-Face-Repo-Guide.md | 22 +++++++++++++------ 4 files changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/wiki-guide/HF_DatasetCard_Template_ABC.md b/docs/wiki-guide/HF_DatasetCard_Template_ABC.md index e83b113..acb59fc 100644 --- a/docs/wiki-guide/HF_DatasetCard_Template_ABC.md +++ b/docs/wiki-guide/HF_DatasetCard_Template_ABC.md @@ -17,9 +17,8 @@ description: # Add a short description (summary) of your dataset, this will rend NOTE: Add more tags (your particular animal, type of model and use-case, etc.). -As with your GitHub Project repo, it is important to choose an appropriate license for your dataset. The default license is [CC0](https://creativecommons.org/publicdomain/zero/1.0/) (public domain dedication, see [Dryad's explanation of why to use CC0](https://blog.datadryad.org/2023/05/30/good-data-practices-removing-barriers-to-data-reuse-with-cc0-licensing/)). Alongside the appropriate stakeholders (eg., your PI, co-authors), select a license that is [Open Source Initiative](https://opensource.org/licenses) (OSI) compliant. -For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com) and [A Quick Guide to Software Licensing for the Scientist-Programmer](https://doi.org/10.1371/journal.pcbi.1002598) by A. Morin, et al. -See the [ABC Global Center policy for licensing](https://docs.google.com/document/d/1SlITG-r7kdJB6C8f4FCJ9Z7o7ccwldZoSRJKjhRAWVA/edit#heading=h.c1sxg0wsiqru) for more information. +As with your GitHub Project repo, it is important to choose an appropriate license for your dataset. The default license is [CC0](https://creativecommons.org/publicdomain/zero/1.0/) (public domain dedication, see [Dryad's explanation of why to use CC0](https://blog.datadryad.org/2023/05/30/good-data-practices-removing-barriers-to-data-reuse-with-cc0-licensing/)). Alongside the appropriate stakeholders (eg., your PI, co-authors), select a license that is following the guidelines set forth in the [ABC Digital Products Release and Licensing Policy](https://ABC-Center.github.io/ABC-guide/wiki-guide/Digital-products-release-licensing-policy/). For Datasets, this would be public domain or terms no more restrictive than requiring attribution (e.g., [CC-BY](https://creativecommons.org/licenses/by/4.0/)). +For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com). List of [HF license identifiers](https://huggingface.co/docs/hub/en/repositories-licenses) (for yaml). See more options for the above information by clicking "edit dataset card" on your repo. diff --git a/docs/wiki-guide/HF_DatasetCard_Template_mkdocs.md b/docs/wiki-guide/HF_DatasetCard_Template_mkdocs.md index ebe9924..d417708 100644 --- a/docs/wiki-guide/HF_DatasetCard_Template_mkdocs.md +++ b/docs/wiki-guide/HF_DatasetCard_Template_mkdocs.md @@ -2,6 +2,9 @@ Below is the Dataset Card template for ABC. You can download or copy the dataset card content and paste it into a new Markdown file to create a README for your dataset. +!!! tip "Pro tip" + Use the [Data Card Checklist](Data-Checklist.md) to help keep track of your progress. +
ABC
diff --git a/docs/wiki-guide/HF_ModelCard_Template_mkdocs.md b/docs/wiki-guide/HF_ModelCard_Template_mkdocs.md index b224195..9a8c6e4 100644 --- a/docs/wiki-guide/HF_ModelCard_Template_mkdocs.md +++ b/docs/wiki-guide/HF_ModelCard_Template_mkdocs.md @@ -2,6 +2,9 @@ Below is the Model Card template for ABC. You can download or copy the model card content and paste it into a new Markdown file to create a README for your model repo. +!!! tip "Pro tip" + Use the [Model Card Checklist](Model-Checklist.md) to help keep track of your progress. +
ABC
diff --git a/docs/wiki-guide/Hugging-Face-Repo-Guide.md b/docs/wiki-guide/Hugging-Face-Repo-Guide.md index ba52275..1539afb 100644 --- a/docs/wiki-guide/Hugging-Face-Repo-Guide.md +++ b/docs/wiki-guide/Hugging-Face-Repo-Guide.md @@ -6,33 +6,41 @@ Need a repository to store your data or model? You've come to the right place! B ### Standard Files -For each repository, include the following files in the root directory as soon as possible; a license can (and should) be instantiated when you create a new repository, and the standard `.gitattributes` will be generated for you. On the [ABC HF](https://huggingface.co/ABC-Center) select `New` and pick which type of repository you need. +For each repository, include the following files and metadata in the root directory as soon as possible; a license can (and should) be instantiated with the Dataset or Model card (`README.md`), and the standard `.gitattributes` will be generated for you. On the [ABC HF](https://huggingface.co/ABC-Center) select `New` and pick which type of repository you need. - [README.md](#readme) -- [LICENSE.md](#license) +- [License](#license) - [.gitignore](#gitignore) - [.gitattributes](#gitattributes) +!!! note + Hugging Face does not support the use of a `CITATION.cff`. Instead, citation guidance is provided in the Citation Section of the [Dataset](HF_DatasetCard_Template_mkdocs.md) or [Model](HF_ModelCard_Template_mkdocs.md) card. When [generating a DOI on Hugging Face](DOI-Generation.md##1-generate-a-doi-on-hugging-face), author names must be added manually in the intended order for them to be displayed in the DOI "Cite this dataset" link. + #### README The README.md file is generally referred to as either a Dataset or Model Card and is what everyone will notice first when they open your repository on Hugging Face. Choose the appropriate ABC-specific HF template ([model](HF_ModelCard_Template_mkdocs.md) or [dataset](HF_DatasetCard_Template_mkdocs.md)) to get started. Be sure to include a brief description and as much information as possible at the beginning. You can update this file as you go, so don't remove the recommended sections prior to completion. The templates include descriptions of many fields, ABC grant information, citation formatting, and some notes on HF-flavored markdown to get you started. Once you've created your repo, populate your README (you can do this online by selecting "Create Dataset/Model Card" and pasting in the appropriate ABC HF template, then filling in your info). Editing your README in the browser allows you to preview the formatting of the file before committing changes. -#### LICENSE +#### License ##### 1. Select a license -Alongside the appropriate stakeholders, select a license that is [Open Source Initiative](https://opensource.org/licenses) (OSI) compliant. +Alongside the appropriate stakeholders, select a license following the guidelines set forth in the [Digital Products Release and Licensing Policy](Digital-products-release-licensing-policy.md). For Datasets, this would be public domain or terms no more restrictive than requiring attribution (e.g., [CC-BY](https://creativecommons.org/licenses/by/4.0/)); Models and Spaces should be released under a license that is [Open Source Initiative](https://opensource.org/licenses) (OSI) compliant. !!! note "Remember" A public repository on Hugging Face with no license can be viewed and accessed by others, but unless the author associates a license, it is unclear what others are allowed to do with it legally. Adding an OSI license can help others feel comfortable building off your work! -For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com) and [A Quick Guide to Software Licensing for the Scientist-Programmer](https://doi.org/10.1371/journal.pcbi.1002598) by A. Morin, et al. +For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com). Keep in mind that your available license options may also be limited by your data sources or base model. Data should not be republished where not explicitly warranted or required.[^1] + +[^1]: For instance, when working with images aggregated from multiple sources, a catalog of all images used with URLs to access the images and download instructions ([cautious-robot](Helpful-Tools-for-your-Workflow.md#cautious-robot) can help with this) respects the original source data producers interests. However, if you have processed the images in a resource-intensive pipeline and the image licenses allow, the _processed_ images should be published for ease of re-use. In this case, it is important to provide the citation for the source data as well. + +##### 2. Add a license to the repository -##### 2. Add LICENSE.md to the repository +Once a license has been chosen (if not initialized with one), add the appropriate license identifier in the `yaml` portion of the README (the web UI generates a dropdown of recommendations under "Edit dataset/model card", [license identifiers](https://huggingface.co/docs/hub/en/repositories-licenses)). -Once a license has been chosen (if not initialized with one), add the appropriate license label in the `yaml` portion of the README (the web UI generates a dropdown of recommendations under "Edit dataset/model card"). +!!! note + Unlike in GitHub, a `LICENSE.md` file is not supported. Instead, the license for the digital object is added through the `yaml` (for ease of API access) and further clarifications can be included in the License Section of the [Dataset](HF_DatasetCard_Template_mkdocs.md) or [Model](HF_ModelCard_Template_mkdocs.md) card. #### gitignore From 705c99405fd2e257cd5523287d47b402838087b7 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Wed, 28 Jan 2026 16:50:11 -0500 Subject: [PATCH 2/3] fix: replace incorrect "eg." with "e.g." throughout project Pull from Collab Guide [PR 55](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/55) Closes #54 --- docs/wiki-guide/Code-Checklist.md | 2 +- docs/wiki-guide/GitHub-Repo-Guide.md | 6 +++--- docs/wiki-guide/HF_DatasetCard_Template_ABC.md | 2 +- docs/wiki-guide/HF_ModelCard_Template_ABC.md | 2 +- docs/wiki-guide/Hugging-Face-Repo-Guide.md | 4 ++-- docs/wiki-guide/The-Hugging-Face-Workflow.md | 2 +- docs/wiki-guide/Two-Repo-Problem.md | 2 +- docs/wiki-guide/Virtual-Environments.md | 2 +- docs/wiki-guide/When-to-think-about-branch-protections.md | 4 ++-- 9 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/wiki-guide/Code-Checklist.md b/docs/wiki-guide/Code-Checklist.md index de0f447..06abe73 100644 --- a/docs/wiki-guide/Code-Checklist.md +++ b/docs/wiki-guide/Code-Checklist.md @@ -19,7 +19,7 @@ This checklist provides an overview of essential and recommended elements to inc - [ ] Acknowledge source code dependencies and contributors. - [ ] Reference related datasets used in training or evaluation. - [ ] **Requirements File**: Provide a [file detailing software requirements](GitHub-Repo-Guide.md/#software-requirements-file), such as a `requirements.txt` or `pyproject.toml` for Python dependencies. -- [ ] **Gitignore File**: GitHub has premade `.gitignore` files (see [github/gitignore](https://github.com/github/gitignore)) tailored to particular languages (eg., [R](https://github.com/github/gitignore/blob/main/R.gitignore) or [Python](https://github.com/github/gitignore/blob/main/Python.gitignore)), operating systems, etc. +- [ ] **Gitignore File**: GitHub has premade `.gitignore` files (see [github/gitignore](https://github.com/github/gitignore)) tailored to particular languages (e.g., [R](https://github.com/github/gitignore/blob/main/R.gitignore) or [Python](https://github.com/github/gitignore/blob/main/Python.gitignore)), operating systems, etc. - [ ] **CITATION CFF**: This facilitates citation of your work, follow guidance provided in the [Repo Guide](GitHub-Repo-Guide.md/#citation). ### Data-Related diff --git a/docs/wiki-guide/GitHub-Repo-Guide.md b/docs/wiki-guide/GitHub-Repo-Guide.md index 6cf35db..8231805 100644 --- a/docs/wiki-guide/GitHub-Repo-Guide.md +++ b/docs/wiki-guide/GitHub-Repo-Guide.md @@ -82,7 +82,7 @@ Once a license has been chosen, add a `LICENSE.md` file to the root of the repos The `.gitignore` file is an important tool for maintaining a clean repository by ensuring that git will not track temp files of any and all your collaborators (no pesky `pycache` or `.DS_Store` files floating around). -GitHub has premade `.gitignore` files which can be selected from a dropdown when creating a repo. They are available for review at [github/gitignore](https://github.com/github/gitignore) and are generally tailored to particular languages (eg., [R](https://github.com/github/gitignore/blob/main/R.gitignore) or [Python](https://github.com/github/gitignore/blob/main/Python.gitignore)), operating systems, etc. The initial choice can be updated as needed. In particular, we recommend selecting a template based on the primary language used for your work. +GitHub has premade `.gitignore` files which can be selected from a dropdown when creating a repo. They are available for review at [github/gitignore](https://github.com/github/gitignore) and are generally tailored to particular languages (e.g., [R](https://github.com/github/gitignore/blob/main/R.gitignore) or [Python](https://github.com/github/gitignore/blob/main/Python.gitignore)), operating systems, etc. The initial choice can be updated as needed. In particular, we recommend selecting a template based on the primary language used for your work. If you or anyone on your team uses a Mac (or if you intend to encourage outside collaboration on this repo), add @@ -95,7 +95,7 @@ at the end of the `.gitignore` file. ### Software Requirements File -It is also advisable to include a machine-readable file with minimal software requirements for your project. For Python projects, this often takes the form of a `requirements.txt` file containing the packages and their versions that were used (eg., `pandas==2.0.1`). If you use `conda`, you may instead opt for an `environment.yml`. These are essential to ensuring the reproducibility and interoperability of your work (by yourself and others). Note that they should _**not**_ be listed in the README. +It is also advisable to include a machine-readable file with minimal software requirements for your project. For Python projects, this often takes the form of a `requirements.txt` file containing the packages and their versions that were used (e.g., `pandas==2.0.1`). If you use `conda`, you may instead opt for an `environment.yml`. These are essential to ensuring the reproducibility and interoperability of your work (by yourself and others). Note that they should _**not**_ be listed in the README. For more information on managing these environments and generating such files programmatically, see the wiki entry [Virtual Environments](Virtual-Environments.md). @@ -292,6 +292,6 @@ If you would like a specific branch, use `git clone -b ` ### Workflow Summary -Generally, repositories are organized around an ABC Project/Topic/Team, eg., butterflies. These broader topics may contain various projects organized under a GitHub [Team](https://github.com/orgs/ABC-Center/teams) focused on that topic. Both [projects](https://github.com/orgs/ABC-Center/projects?query=is%3Aopen) and [repositories](https://github.com/orgs/ABC-Center/repositories) may be linked to teams, providing an organizational structure upon which to plan and manage tasks while maintaining a clear link/connection to the work being done on those tasks. Note that a project may encapsulate multiple repositories just as a repository may be referenced by multiple projects. +Generally, repositories are organized around an ABC Project/Topic/Team, e.g., butterflies. These broader topics may contain various projects organized under a GitHub [Team](https://github.com/orgs/ABC-Center/teams) focused on that topic. Both [projects](https://github.com/orgs/ABC-Center/projects?query=is%3Aopen) and [repositories](https://github.com/orgs/ABC-Center/repositories) may be linked to teams, providing an organizational structure upon which to plan and manage tasks while maintaining a clear link/connection to the work being done on those tasks. Note that a project may encapsulate multiple repositories just as a repository may be referenced by multiple projects. Ideally, each task will be linked to an issue in the relevant repository. Team members may then be assigned tasks, and asynchronous discussions about the task can be recorded on its issue page in the repository. To accomplish the task, a new branch should be created following the [branch naming conventions](#formatting-and-naming-conventions); do not work directly on the `main` branch. Once the task is completed, a pull request can be opened to merge the changes into the main branch (see the [GitHub Workflow Guide](The-GitHub-Workflow.md) and the [PR Guide](The-GitHub-Pull-Request-Guide.md) for more details on this process). Reviewers may be assigned to each pull request to ensure compatibility and that the proposed solution functions as expected/needed; this is an opportunity for more dialogue. diff --git a/docs/wiki-guide/HF_DatasetCard_Template_ABC.md b/docs/wiki-guide/HF_DatasetCard_Template_ABC.md index acb59fc..1b120e3 100644 --- a/docs/wiki-guide/HF_DatasetCard_Template_ABC.md +++ b/docs/wiki-guide/HF_DatasetCard_Template_ABC.md @@ -17,7 +17,7 @@ description: # Add a short description (summary) of your dataset, this will rend NOTE: Add more tags (your particular animal, type of model and use-case, etc.). -As with your GitHub Project repo, it is important to choose an appropriate license for your dataset. The default license is [CC0](https://creativecommons.org/publicdomain/zero/1.0/) (public domain dedication, see [Dryad's explanation of why to use CC0](https://blog.datadryad.org/2023/05/30/good-data-practices-removing-barriers-to-data-reuse-with-cc0-licensing/)). Alongside the appropriate stakeholders (eg., your PI, co-authors), select a license that is following the guidelines set forth in the [ABC Digital Products Release and Licensing Policy](https://ABC-Center.github.io/ABC-guide/wiki-guide/Digital-products-release-licensing-policy/). For Datasets, this would be public domain or terms no more restrictive than requiring attribution (e.g., [CC-BY](https://creativecommons.org/licenses/by/4.0/)). +As with your GitHub Project repo, it is important to choose an appropriate license for your dataset. The default license is [CC0](https://creativecommons.org/publicdomain/zero/1.0/) (public domain dedication, see [Dryad's explanation of why to use CC0](https://blog.datadryad.org/2023/05/30/good-data-practices-removing-barriers-to-data-reuse-with-cc0-licensing/)). Alongside the appropriate stakeholders (e.g., your PI, co-authors), select a license that is following the guidelines set forth in the [ABC Digital Products Release and Licensing Policy](https://ABC-Center.github.io/ABC-guide/wiki-guide/Digital-products-release-licensing-policy/). For Datasets, this would be public domain or terms no more restrictive than requiring attribution (e.g., [CC-BY](https://creativecommons.org/licenses/by/4.0/)). For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com). List of [HF license identifiers](https://huggingface.co/docs/hub/en/repositories-licenses) (for yaml). See more options for the above information by clicking "edit dataset card" on your repo. diff --git a/docs/wiki-guide/HF_ModelCard_Template_ABC.md b/docs/wiki-guide/HF_ModelCard_Template_ABC.md index f205729..12bac2d 100644 --- a/docs/wiki-guide/HF_ModelCard_Template_ABC.md +++ b/docs/wiki-guide/HF_ModelCard_Template_ABC.md @@ -17,7 +17,7 @@ model_description: # Add a short description (summary) of your model, this will NOTE: Add more tags (your particular animal, type of model and use-case, etc.). -As with your GitHub Project repo, it is important to choose an appropriate license for your model. Alongside the appropriate stakeholders (eg., your PI, co-authors), select a license that is [Open Source Initiative](https://opensource.org/licenses) (OSI) compliant. You may also wish to consider adding a [RAIL license](https://www.licenses.ai/ai-licenses), which addresses responsible use. +As with your GitHub Project repo, it is important to choose an appropriate license for your model. Alongside the appropriate stakeholders (e.g., your PI, co-authors), select a license that is [Open Source Initiative](https://opensource.org/licenses) (OSI) compliant. You may also wish to consider adding a [RAIL license](https://www.licenses.ai/ai-licenses), which addresses responsible use. For more information on how to choose a license and why it matters, see [Choose A License](https://choosealicense.com) and [A Quick Guide to Software Licensing for the Scientist-Programmer](https://doi.org/10.1371/journal.pcbi.1002598) by A. Morin, et al. See the [ABC Global Center policy for licensing](https://docs.google.com/document/d/1SlITG-r7kdJB6C8f4FCJ9Z7o7ccwldZoSRJKjhRAWVA/edit#heading=h.c1sxg0wsiqru) for more information. diff --git a/docs/wiki-guide/Hugging-Face-Repo-Guide.md b/docs/wiki-guide/Hugging-Face-Repo-Guide.md index 1539afb..0c9848f 100644 --- a/docs/wiki-guide/Hugging-Face-Repo-Guide.md +++ b/docs/wiki-guide/Hugging-Face-Repo-Guide.md @@ -57,7 +57,7 @@ at the end of the `.gitignore` file. #### gitattributes -The `.gitattributes` file determines file patterns to be tracked by [`git LFS`](https://git-lfs.com/) (Git Large File Storage). The preset `gitattributes` file includes many binary file types, but you may need to add particular files if they get too large (eg., a large CSV, but do **NOT** store all CSV files with `git LFS`, just add the particular one or pattern). Pattern-matching can be done using `*`. You can either add the file (and appropriate pattern description) to the `.gitattributes` file, or add it in the command line: +The `.gitattributes` file determines file patterns to be tracked by [`git LFS`](https://git-lfs.com/) (Git Large File Storage). The preset `gitattributes` file includes many binary file types, but you may need to add particular files if they get too large (e.g., a large CSV, but do **NOT** store all CSV files with `git LFS`, just add the particular one or pattern). Pattern-matching can be done using `*`. You can either add the file (and appropriate pattern description) to the `.gitattributes` file, or add it in the command line: ``` git lfs track "my-big-list.csv" @@ -69,7 +69,7 @@ Then add and commit the `.gitattributes` file as described below. Hugging Face also has a pull request (PR) feature, though the process is a bit different from GitHub. -As with GitHub, you can interact through the web browser or a command line interface (eg., terminal on Mac). However, instead of the `create new branch` option, there is a `create new pull request` option. It is still preferable to avoid committing everything directly to main. To make further changes to the particular PR created on the browser, one must first clone the repo: +As with GitHub, you can interact through the web browser or a command line interface (e.g., terminal on Mac). However, instead of the `create new branch` option, there is a `create new pull request` option. It is still preferable to avoid committing everything directly to main. To make further changes to the particular PR created on the browser, one must first clone the repo: ``` git clone diff --git a/docs/wiki-guide/The-Hugging-Face-Workflow.md b/docs/wiki-guide/The-Hugging-Face-Workflow.md index 75f0157..0867afc 100644 --- a/docs/wiki-guide/The-Hugging-Face-Workflow.md +++ b/docs/wiki-guide/The-Hugging-Face-Workflow.md @@ -4,7 +4,7 @@ Hugging Face also has a pull request (PR) feature, though the process is a bit different from GitHub. -As with GitHub, you can interact through the web browser or a command line interface (eg., terminal on Mac). However, instead of the `create new branch` option, there is a `create new pull request` option. It is still preferable to avoid committing everything directly to main. To make further changes to the particular PR created on the browser, one must first clone the repo: +As with GitHub, you can interact through the web browser or a command line interface (e.g., terminal on Mac). However, instead of the `create new branch` option, there is a `create new pull request` option. It is still preferable to avoid committing everything directly to main. To make further changes to the particular PR created on the browser, one must first clone the repo: ``` git clone diff --git a/docs/wiki-guide/Two-Repo-Problem.md b/docs/wiki-guide/Two-Repo-Problem.md index 5f4077e..c733851 100644 --- a/docs/wiki-guide/Two-Repo-Problem.md +++ b/docs/wiki-guide/Two-Repo-Problem.md @@ -196,7 +196,7 @@ git push --set-upstream origin v1 At this point the main branch of the public repo should match the main branch of the private repo. Additional changes should be made only to the private repo, preferably using a branch. See [Github-Workflow](The-GitHub-Workflow.md) for more details. -When you are ready to release a new version of the code in the private repo follow the [Merge Private to Public instructions](#merge-private-to-public) again using a new version branch name (eg. `v2`). +When you are ready to release a new version of the code in the private repo follow the [Merge Private to Public instructions](#merge-private-to-public) again using a new version branch name (e.g., `v2`). *** diff --git a/docs/wiki-guide/Virtual-Environments.md b/docs/wiki-guide/Virtual-Environments.md index 5d16944..026b3e0 100644 --- a/docs/wiki-guide/Virtual-Environments.md +++ b/docs/wiki-guide/Virtual-Environments.md @@ -32,7 +32,7 @@ conda env export --no-builds --from-history | grep -v "prefix" > environment.yml For virtual environments using `pip` to install packages (Python environments), use `python -m pip freeze` to print a list of packages (and their versions) installed in the environment. !!! info "Command extension" - - `python -m pip freeze > requirements.txt` will populate a `requirements.txt` file with all these packages and versions listed (eg., `pandas==2.0.1`). + - `python -m pip freeze > requirements.txt` will populate a `requirements.txt` file with all these packages and versions listed (e.g., `pandas==2.0.1`). - **Note:** This will _not_ give only minimum software requirements, but will also print _all_ dependencies. - Install this machine-readable file with `pip install -r requirements.txt` when in the appropriate folder. - For more information, see the [pip documentation](https://pip.pypa.io/en/stable/cli/pip_freeze/). diff --git a/docs/wiki-guide/When-to-think-about-branch-protections.md b/docs/wiki-guide/When-to-think-about-branch-protections.md index 02ef0d5..b3440e4 100644 --- a/docs/wiki-guide/When-to-think-about-branch-protections.md +++ b/docs/wiki-guide/When-to-think-about-branch-protections.md @@ -10,7 +10,7 @@ Generally speaking, once the set of potential users exceeds that of repository d ## How to Implement Branch Protections -From your repository, navigate to "Settings" and select "Branches" from the left toolbar. Provide the name of the branch you would like to protect, for instance `main`, and select the rules that you want applied to the branch. It is also possible to set the rules for branches matching a particular pattern (eg., type `*release*` to apply the rules to any branch containing the word `release`). You can also edit branch protection rules from this page. +From your repository, navigate to "Settings" and select "Branches" from the left toolbar. Provide the name of the branch you would like to protect, for instance `main`, and select the rules that you want applied to the branch. It is also possible to set the rules for branches matching a particular pattern (e.g., type `*release*` to apply the rules to any branch containing the word `release`). You can also edit branch protection rules from this page. The example below shows the addition of branch protection rules for `main` that require a pull request and that it be approved prior to merging. It also will remove approval if other changes are added that require approval. @@ -40,7 +40,7 @@ We choose to apply these to the default branch (`main` or `master`). /// caption /// -As with branch protections, it is also possible to set the rules for branches matching a particular pattern (eg., type `*release*` to apply the rules to any branch containing the word `release`). We will do this for `gh-pages`. +As with branch protections, it is also possible to set the rules for branches matching a particular pattern (e.g., type `*release*` to apply the rules to any branch containing the word `release`). We will do this for `gh-pages`. ![Add target pattern for gh-pages under target branches for branch ruleset](images/GH-branch-protections/382111988-20d6499e-fb12-4335-8b8d-76ac6b989528.png){ loading=lazy } /// caption From dd3c1432d3ac4898ec6a1eee24ab4ac82a81ba65 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Thu, 29 Jan 2026 08:53:29 -0500 Subject: [PATCH 3/3] docs(tools): add Vale prose linter section Pull from Collab Guide [PR 23](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/23) * docs(tools): add Vale prose linter section * Update docs/wiki-guide/Helpful-Tools-for-your-Workflow.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/wiki-guide/Helpful-Tools-for-your-Workflow.md Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> * Add hyperlinks to Vale style guides in documentation (#56) * Initial plan * Add hyperlinks to Vale style guides (Google, Microsoft, write-good) Co-authored-by: gwtaylor <993736+gwtaylor@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: gwtaylor <993736+gwtaylor@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: gwtaylor <993736+gwtaylor@users.noreply.github.com> --- .../Helpful-Tools-for-your-Workflow.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md index 6483231..dd90ae9 100644 --- a/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md +++ b/docs/wiki-guide/Helpful-Tools-for-your-Workflow.md @@ -56,6 +56,26 @@ Ruff can also be set up as part of a pre-commit hook or GitHub Workflow. See the Fast _Markdown_ formatter and linter. We use the [DavidAnson/markdownlint](https://github.com/DavidAnson/markdownlint) package for this site; see instructions and example in the [linting section](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/CONTRIBUTING.md#linting) of our contributing guidelines. It is flexible in configuration and allows for simple checking or even fixing straight-forward formatting issues. +### Vale + +Syntax-aware prose linter for documentation, technical writing, and Markdown files. Unlike basic spell checkers, [errata-ai/vale](https://github.com/errata-ai/vale) enforces customizable style guides and writing rules, making it ideal for maintaining consistency across project documentation. You can install it with `brew install vale` on macOS, or see the [installation guide](https://vale.sh/docs/vale-cli/installation/) for other platforms. + +Vale comes with support for popular style guides like [Google](https://github.com/errata-ai/Google), [Microsoft](https://github.com/errata-ai/Microsoft), and [write-good](https://github.com/errata-ai/write-good), and you can create custom rules for your project's specific needs. It integrates well with version control workflows and can check documentation in various formats including Markdown, reStructuredText, HTML, and AsciiDoc. + +To lint documentation files, run: + +```bash +vale +``` + +To check an entire directory: + +```bash +vale docs/ +``` + +Vale uses a `.vale.ini` configuration file in your project root to specify style guides, vocabulary, and which files to check. You can also set up Vale as part of a [pre-commit](https://pre-commit.com/) hook or GitHub Workflow to automatically check documentation on commits or pull requests. See the [Vale documentation](https://vale.sh/docs/) for configuration examples and style guide options. + ## FAIR Data Access and Validation Don't add to the reproducibility crisis! Are you using existing data accessed through URLs and need to ensure consistency for re-use? Do you have a folder of images with all their metadata documented through their filenames? [Cautious Robot](#cautious-robot) and [Sum Buddy](#sum-buddy) are here to help.