From 95487443e174c6bb1365857cd40992e74744507d Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Wed, 23 Jul 2025 09:06:27 -0400 Subject: [PATCH 1/7] docs: add CONTRIBUTING.md with project standards and guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document markdown formatting standards including 4-space indentation requirement - Specify license format requirements for Hugging Face compatibility - Include local development setup and testing procedures - Add quality assurance guidelines and platform-specific considerations - Include conventional commits standard for commit messages - Reference existing tools and configurations Resolves #55 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CONTRIBUTING.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7bb782d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,177 @@ +# Contributing to Imageomics Guide + +Thank you for your interest in contributing to the Imageomics Guide! This document outlines the standards and guidelines for contributing to this project. + +## Overview + +The Imageomics Guide is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and deployed via GitHub Pages. All documentation is written in Markdown and follows specific formatting standards to ensure consistent rendering and maintainability. + +## Getting Started + +### Local Development Setup + +1. Clone the repository +2. Install dependencies: + ```bash + pip install -r requirements.txt + ``` +3. Serve the site locally: + ```bash + mkdocs serve + ``` +4. View the site at http://127.0.0.1:8000/Imageomics-guide/ + +### Testing Changes + +Always test your changes locally with `mkdocs serve` before submitting a PR to ensure: +- Content renders correctly +- Links work properly +- Formatting appears as intended +- No build errors occur + +## Documentation Standards + +### Markdown Formatting + +#### Indentation for Nested Lists +- **Use 4 spaces for nested list items** (not 2 spaces) +- This requirement exists due to Python-Markdown compatibility issues with MkDocs +- 2-space indentation causes nested lists to not render properly in the final HTML + +**Correct:** +```markdown +- [ ] Main item + - [ ] Nested item + - [ ] Another nested item +``` + +**Incorrect:** +```markdown +- [ ] Main item + - [ ] Nested item (will not render as nested) +``` + +#### General Formatting +- Remove trailing whitespace +- Use consistent line breaks +- Follow the project's `.markdownlint.json` configuration +- Ensure proper heading hierarchy (don't skip heading levels) + +### License Format Requirements + +#### Hugging Face YAML Frontmatter +When specifying licenses in Hugging Face dataset/model card YAML sections, **always use lowercase**: + +**Correct:** +```yaml +license: cc0-1.0 +``` + +**Incorrect:** +```yaml +license: CC0-1.0 # Will cause issues with Hugging Face platform +``` + +This is a platform-specific requirement for Hugging Face compatibility. + +#### License References in Text +In prose text, you may use standard capitalization (e.g., "CC0", "MIT"), but YAML frontmatter must be lowercase. + +### File Organization + +- Documentation content goes in `docs/` +- Wiki-style guides go in `docs/wiki-guide/` +- Images and assets are organized in subdirectories within `docs/` +- Templates use descriptive filenames with consistent naming patterns + +### Custom Macros + +The project includes custom MkDocs macros defined in `main.py`: +- `include_file_as_code()` - Embeds file content as code blocks +- When using macros, ensure proper syntax and test rendering locally + +## Contribution Process + +1. **Create an issue** describing the change (for significant additions) +2. **Create a feature branch** from `main` +3. **Make your changes** following the standards above +4. **Test locally** with `mkdocs serve` +5. **Run linting** to ensure formatting consistency +6. **Submit a pull request** with: + - Clear description of changes + - Reference to related issue + - Screenshots if UI changes are involved + +### Pull Request Guidelines + +- Keep PRs focused on a single topic when possible +- Follow commit message conventions (see below) +- Update navigation in `mkdocs.yaml` if adding new pages +- Ensure all links work correctly +- Test that the site builds without errors + +### Commit Message Guidelines + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for commit messages: + +**Format:** `type(scope): description` + +**Common types:** +- `feat`: New feature or content addition +- `fix`: Bug fix or correction +- `docs`: Documentation updates +- `style`: Formatting changes (no content changes) +- `refactor`: Code/content restructuring without changing functionality +- `chore`: Maintenance tasks, tooling updates + +**Examples:** +``` +feat(fair-guide): add data repository checklist +fix(templates): correct license format in HF dataset card +docs(contributing): add conventional commit guidelines +style(checklists): fix markdown formatting and indentation +chore: update mkdocs dependencies +``` + +**Scope** is optional but helpful for larger changes. Use the guide section or file type being modified. + +## Quality Assurance + +### Linting +The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. Key settings: +- 4-space indentation for lists (`MD007`) +- No hard tab restrictions disabled +- Line length restrictions disabled (`MD013`) + +### Content Review +When reviewing content: +- Verify accuracy of technical information +- Check for consistency with existing guides +- Ensure proper cross-referencing between related pages +- Validate that external links are current and working + +## Platform-Specific Considerations + +### Hugging Face Integration +- Dataset and model card templates must follow HF specifications +- YAML frontmatter formatting is critical for platform compatibility +- License identifiers must match HF's expected format + +### MkDocs/Python-Markdown +- Nested list rendering requires specific indentation +- Some Markdown extensions may behave differently than GitHub Flavored Markdown +- Always test complex formatting locally + +## Getting Help + +- Open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) for questions or problems +- Reference existing guides and templates for examples +- Check the [MkDocs Material documentation](https://squidfunk.github.io/mkdocs-material/) for advanced features + +## Code of Conduct + +All contributors must adhere to our [Code of Conduct](docs/CODE_OF_CONDUCT.md) and Imageomics Institute Principles of Engagement. + +--- + +Thank you for helping improve the Imageomics Guide! Your contributions help make collaborative scientific computing more accessible and effective. \ No newline at end of file From 636aa99cf6560224c6b70519cdffec6ef5cfd2bf Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Wed, 23 Jul 2025 09:11:50 -0400 Subject: [PATCH 2/7] docs: add Contributing section to README References CONTRIBUTING.md to help new contributors find project guidelines --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index bf7b3b2..e1a9fc8 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,10 @@ This guide started as an Institute-internal wiki, focused on providing guidance Please feel free to open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) with any questions regarding the content fo this guide or if you would like to contribute to the [Glossary](https://imageomics.github.io/Imageomics-guide/wiki-guide/Glossary-for-Imageomics/) or [Helpful Tools page](https://imageomics.github.io/Imageomics-guide/wiki-guide/Helpful-Tools-for-your-Workflow/). +## Contributing + +If you'd like to contribute to this guide, please read our [Contributing Guidelines](CONTRIBUTING.md) for information about our standards, development workflow, and submission process. + ### Testing To test this site locally, first clone this repository, then create an environment with `requirements.txt` ``` From 384817dc4aee2ce93cd736bb094d02f470b6fc00 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Mon, 28 Jul 2025 19:59:08 -0400 Subject: [PATCH 3/7] docs(contributing): update commit message guidelines per review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Restructure to emphasize descriptive and atomic commits as primary goals - Add 50-character limit guideline for commit subject lines - Change Conventional Commits from standard to recommendation - Add note about squash merges reducing strict adherence requirement - Fix markdownlint formatting issues 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CONTRIBUTING.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7bb782d..589f11e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,11 +112,20 @@ The project includes custom MkDocs macros defined in `main.py`: ### Commit Message Guidelines -We follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for commit messages: +The most important aspects of good commit messages are that they should be **descriptive** and **atomic** (each commit should represent a single logical change). Additionally: + +- **Keep the first line short**: Limit the subject line to 50 characters or less +- **Use the imperative mood**: "Add feature" not "Added feature" or "Adds feature" +- **Separate subject from body**: Use a blank line between the subject line and detailed description + +#### Conventional Commits Recommendation + +We recommend following the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages: **Format:** `type(scope): description` **Common types:** + - `feat`: New feature or content addition - `fix`: Bug fix or correction - `docs`: Documentation updates @@ -125,7 +134,8 @@ We follow the [Conventional Commits](https://www.conventionalcommits.org/) stand - `chore`: Maintenance tasks, tooling updates **Examples:** -``` + +```bash feat(fair-guide): add data repository checklist fix(templates): correct license format in HF dataset card docs(contributing): add conventional commit guidelines @@ -135,15 +145,19 @@ chore: update mkdocs dependencies **Scope** is optional but helpful for larger changes. Use the guide section or file type being modified. +**Note:** Since we use squash merges, strict adherence to this format isn't required, but descriptive and atomic commits help maintain a clear project history. + ## Quality Assurance ### Linting + The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. Key settings: - 4-space indentation for lists (`MD007`) - No hard tab restrictions disabled - Line length restrictions disabled (`MD013`) ### Content Review + When reviewing content: - Verify accuracy of technical information - Check for consistency with existing guides @@ -153,11 +167,13 @@ When reviewing content: ## Platform-Specific Considerations ### Hugging Face Integration + - Dataset and model card templates must follow HF specifications - YAML frontmatter formatting is critical for platform compatibility - License identifiers must match HF's expected format ### MkDocs/Python-Markdown + - Nested list rendering requires specific indentation - Some Markdown extensions may behave differently than GitHub Flavored Markdown - Always test complex formatting locally @@ -174,4 +190,4 @@ All contributors must adhere to our [Code of Conduct](docs/CODE_OF_CONDUCT.md) a --- -Thank you for helping improve the Imageomics Guide! Your contributions help make collaborative scientific computing more accessible and effective. \ No newline at end of file +Thank you for helping improve the Imageomics Guide! Your contributions help make collaborative scientific computing more accessible and effective. From ba8c515b2638d7201cf9afb447dcf5520a754722 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Mon, 28 Jul 2025 20:12:28 -0400 Subject: [PATCH 4/7] docs(contributing): update for template repository transformation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Change title from "Imageomics Guide" to "Collaborative Distributed Science Guide" - Add context about template repository nature for organizations - Update branch workflow from main to dev branch - Update repository URLs to new template naming - Generalize Code of Conduct reference to "organizational principles" Addresses review feedback from @egrace479 in PR #56 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CONTRIBUTING.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 589f11e..1df04e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,12 @@ -# Contributing to Imageomics Guide +# Contributing to Collaborative Distributed Science Guide -Thank you for your interest in contributing to the Imageomics Guide! This document outlines the standards and guidelines for contributing to this project. +Thank you for your interest in contributing to the Collaborative Distributed Science Guide! This document outlines the standards and guidelines for contributing to this template repository. ## Overview -The Imageomics Guide is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and deployed via GitHub Pages. All documentation is written in Markdown and follows specific formatting standards to ensure consistent rendering and maintainability. +The Collaborative Distributed Science Guide is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and deployed via GitHub Pages. All documentation is written in Markdown and follows specific formatting standards to ensure consistent rendering and maintainability. + +This is a template repository designed to be forked and customized by different organizations for their collaborative science documentation needs. ## Getting Started @@ -19,7 +21,7 @@ The Imageomics Guide is built with [MkDocs Material](https://squidfunk.github.io ```bash mkdocs serve ``` -4. View the site at http://127.0.0.1:8000/Imageomics-guide/ +4. View the site at http://127.0.0.1:8000/Collaborative-distributed-science-guide/ ### Testing Changes @@ -93,7 +95,7 @@ The project includes custom MkDocs macros defined in `main.py`: ## Contribution Process 1. **Create an issue** describing the change (for significant additions) -2. **Create a feature branch** from `main` +2. **Create a feature branch** from `dev` 3. **Make your changes** following the standards above 4. **Test locally** with `mkdocs serve` 5. **Run linting** to ensure formatting consistency @@ -180,14 +182,14 @@ When reviewing content: ## Getting Help -- Open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) for questions or problems +- Open an [issue](https://github.com/Imageomics/Collaborative-distributed-science-guide/issues) for questions or problems - Reference existing guides and templates for examples - Check the [MkDocs Material documentation](https://squidfunk.github.io/mkdocs-material/) for advanced features ## Code of Conduct -All contributors must adhere to our [Code of Conduct](docs/CODE_OF_CONDUCT.md) and Imageomics Institute Principles of Engagement. +All contributors must adhere to our [Code of Conduct](docs/CODE_OF_CONDUCT.md) and organizational principles of engagement. --- -Thank you for helping improve the Imageomics Guide! Your contributions help make collaborative scientific computing more accessible and effective. +Thank you for helping improve the Collaborative Distributed Science Guide! Your contributions help make collaborative scientific computing more accessible and effective. From 5c11c1119b244674391eb714679816af419d6c45 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Mon, 28 Jul 2025 20:17:40 -0400 Subject: [PATCH 5/7] docs(contributing): add virtual environment setup to local development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add virtual environment creation step with cross-platform commands - Link to Virtual Environments guide for detailed options including conda - Update step numbering for proper sequence - Address review feedback from @egrace479 about environment setup 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1df04e3..e39de5d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,15 +13,21 @@ This is a template repository designed to be forked and customized by different ### Local Development Setup 1. Clone the repository -2. Install dependencies: +2. Set up a virtual environment (recommended): + ```bash + python -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + ``` + For more detailed environment setup options (including conda), see our [Virtual Environments guide](docs/wiki-guide/Virtual-Environments.md). +3. Install dependencies: ```bash pip install -r requirements.txt ``` -3. Serve the site locally: +4. Serve the site locally: ```bash mkdocs serve ``` -4. View the site at http://127.0.0.1:8000/Collaborative-distributed-science-guide/ +5. View the site at http://127.0.0.1:8000/Collaborative-distributed-science-guide/ ### Testing Changes From 75e03e32b06f9497bbef4a595d231350837079da Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Mon, 28 Jul 2025 20:22:09 -0400 Subject: [PATCH 6/7] style(contributing): fix markdownlint formatting issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add blank lines around fenced code blocks (MD031) - Add blank lines around lists (MD032) - Add blank lines around headings (MD022) - Fix bare URL formatting (MD034) - Ensure consistent markdown formatting throughout 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CONTRIBUTING.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e39de5d..4214d10 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,24 +14,32 @@ This is a template repository designed to be forked and customized by different 1. Clone the repository 2. Set up a virtual environment (recommended): + ```bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` + For more detailed environment setup options (including conda), see our [Virtual Environments guide](docs/wiki-guide/Virtual-Environments.md). + 3. Install dependencies: + ```bash pip install -r requirements.txt ``` + 4. Serve the site locally: + ```bash mkdocs serve ``` -5. View the site at http://127.0.0.1:8000/Collaborative-distributed-science-guide/ + +5. View the site at ### Testing Changes Always test your changes locally with `mkdocs serve` before submitting a PR to ensure: + - Content renders correctly - Links work properly - Formatting appears as intended @@ -42,11 +50,13 @@ Always test your changes locally with `mkdocs serve` before submitting a PR to e ### Markdown Formatting #### Indentation for Nested Lists + - **Use 4 spaces for nested list items** (not 2 spaces) - This requirement exists due to Python-Markdown compatibility issues with MkDocs - 2-space indentation causes nested lists to not render properly in the final HTML **Correct:** + ```markdown - [ ] Main item - [ ] Nested item @@ -54,12 +64,14 @@ Always test your changes locally with `mkdocs serve` before submitting a PR to e ``` **Incorrect:** + ```markdown - [ ] Main item - [ ] Nested item (will not render as nested) ``` #### General Formatting + - Remove trailing whitespace - Use consistent line breaks - Follow the project's `.markdownlint.json` configuration @@ -68,14 +80,17 @@ Always test your changes locally with `mkdocs serve` before submitting a PR to e ### License Format Requirements #### Hugging Face YAML Frontmatter + When specifying licenses in Hugging Face dataset/model card YAML sections, **always use lowercase**: **Correct:** + ```yaml license: cc0-1.0 ``` **Incorrect:** + ```yaml license: CC0-1.0 # Will cause issues with Hugging Face platform ``` @@ -83,6 +98,7 @@ license: CC0-1.0 # Will cause issues with Hugging Face platform This is a platform-specific requirement for Hugging Face compatibility. #### License References in Text + In prose text, you may use standard capitalization (e.g., "CC0", "MIT"), but YAML frontmatter must be lowercase. ### File Organization @@ -95,6 +111,7 @@ In prose text, you may use standard capitalization (e.g., "CC0", "MIT"), but YAM ### Custom Macros The project includes custom MkDocs macros defined in `main.py`: + - `include_file_as_code()` - Embeds file content as code blocks - When using macros, ensure proper syntax and test rendering locally @@ -160,6 +177,7 @@ chore: update mkdocs dependencies ### Linting The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. Key settings: + - 4-space indentation for lists (`MD007`) - No hard tab restrictions disabled - Line length restrictions disabled (`MD013`) @@ -167,6 +185,7 @@ The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with ### Content Review When reviewing content: + - Verify accuracy of technical information - Check for consistency with existing guides - Ensure proper cross-referencing between related pages From 54937776fe4a23d792c12507c29a4e0cc7cd9232 Mon Sep 17 00:00:00 2001 From: Graham Taylor Date: Tue, 29 Jul 2025 15:41:19 -0400 Subject: [PATCH 7/7] docs(contributing): add article "the" to guide title Add definite article to "Collaborative Distributed Science Guide" title for improved readability and consistency with standard naming conventions. Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4214d10..8341666 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to Collaborative Distributed Science Guide +# Contributing to the Collaborative Distributed Science Guide Thank you for your interest in contributing to the Collaborative Distributed Science Guide! This document outlines the standards and guidelines for contributing to this template repository.