Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/wiki-guide/Code-Checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/wiki-guide/GitHub-Repo-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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).

Expand Down Expand Up @@ -292,6 +292,6 @@ If you would like a specific branch, use `git clone -b <branch_name> <repo_url>`

### 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.
5 changes: 2 additions & 3 deletions docs/wiki-guide/HF_DatasetCard_Template_ABC.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 (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.

Expand Down
3 changes: 3 additions & 0 deletions docs/wiki-guide/HF_DatasetCard_Template_mkdocs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details open>
<summary>ABC</summary>
</br>
Expand Down
2 changes: 1 addition & 1 deletion docs/wiki-guide/HF_ModelCard_Template_ABC.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 3 additions & 0 deletions docs/wiki-guide/HF_ModelCard_Template_mkdocs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details open>
<summary>ABC</summary>
</br>
Expand Down
20 changes: 20 additions & 0 deletions docs/wiki-guide/Helpful-Tools-for-your-Workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <path/to/file.md>
```

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.
Expand Down
Loading