Skip to content

Conversation

gwtaylor
Copy link
Collaborator

Summary

Adds a comprehensive CONTRIBUTING.md file to document project-specific standards and guidelines that have been identified through PR reviews, particularly during the FAIR Guide implementation in #37.

Changes

  • Project Standards Documentation: Documents markdown formatting requirements, license format specifications, and technical constraints
  • Development Workflow: Includes local setup, testing procedures, and quality assurance guidelines
  • Commit Guidelines: Adopts conventional commits standard with project-specific examples
  • Platform-Specific Requirements: Documents Hugging Face YAML formatting and MkDocs/Python-Markdown compatibility issues

Key Standards Documented

Markdown Formatting

  • 4-space indentation for nested lists (due to Python-Markdown/MkDocs compatibility)
  • Markdownlint configuration rationale
  • Formatting consistency requirements

License Requirements

  • Lowercase license identifiers in YAML frontmatter (cc0-1.0 not CC0-1.0) for Hugging Face compatibility
  • Platform-specific formatting requirements

Development Process

  • Local testing with mkdocs serve
  • Quality assurance procedures
  • PR submission guidelines

File Placement Decision

The file is placed in the repository root (not in docs/) to leverage GitHub's automatic detection and integration features for contributing guidelines. This follows standard GitHub conventions while noting that we considered placing it in docs/ for consistency with our existing documentation structure.

Testing

  • File renders correctly in GitHub
  • Local MkDocs build still works (mkdocs serve)
  • All links are functional
  • Markdown formatting follows project standards

Resolves #55

Test Plan

  • @egrace479 and @hlapp review content for accuracy and completeness
  • Verify all documented standards reflect current project practices
  • Confirm the conventional commits format works for our workflow
  • Consider if README.md should reference this file

🤖 Generated with Claude Code

- 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 <noreply@anthropic.com>
@gwtaylor gwtaylor requested review from egrace479 and hlapp July 23, 2025 13:07
References CONTRIBUTING.md to help new contributors find project guidelines
@gwtaylor gwtaylor mentioned this pull request Jul 23, 2025
@hlapp hlapp marked this pull request as draft July 25, 2025 21:51
@hlapp
Copy link
Member

hlapp commented Jul 25, 2025

As per online discussion, changed back to draft stage to indicate that more changes are in the works already. Please change back to ready for review once those are in.

Copy link
Member

@hlapp hlapp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Up to here content looks great, many thanks @gwtaylor for your work on this and @egrace479 for comments!

- 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 <noreply@anthropic.com>
@gwtaylor gwtaylor changed the base branch from main to dev July 29, 2025 00:08
gwtaylor and others added 3 commits July 28, 2025 20:12
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
@gwtaylor
Copy link
Collaborator Author

@egrace479 I flagged you to have a check of the commit that implements the dev branch and Collaborative Distributed Science Guide retarget. If you're happy with that, this should be good to merge.

@gwtaylor gwtaylor added the enhancement New feature or request label Jul 29, 2025
@gwtaylor gwtaylor marked this pull request as ready for review July 29, 2025 11:00
Copy link
Member

@egrace479 egrace479 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great! Just one small change to add the article in the title (as it is there throughout). Approving with this single change request.

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>
@gwtaylor gwtaylor force-pushed the add-contributing-guidelines branch from ad954f7 to 5493777 Compare July 29, 2025 19:46
@gwtaylor gwtaylor merged commit d676b24 into dev Jul 29, 2025
gwtaylor added a commit that referenced this pull request Jul 29, 2025
#56)

- Add CONTRIBUTING.md with markdown formatting requirements
- Document license format specifications for Hugging Face compatibility
- Include development workflow and testing procedures
- Adopt conventional commits standard with project examples
- Add quality assurance guidelines and platform-specific requirements

Resolves #55
@egrace479 egrace479 deleted the add-contributing-guidelines branch July 30, 2025 14:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add CONTRIBUTING.md to document project standards and guidelines
3 participants