Skip to content

Add CONTRIBUTING.md to document project standards and guidelines #55

@gwtaylor

Description

@gwtaylor

Background

During PR review #37, we identified several project-specific standards and technical requirements that should be documented for consistency across contributions. Currently, these standards exist implicitly in our codebase but aren't documented anywhere for contributors to reference.

Problem

Without documented contribution guidelines, contributors may:

  • Use inconsistent markdown formatting
  • Miss platform-specific requirements (e.g., HuggingFace YAML formatting)
  • Be unaware of technical constraints (e.g., MkDocs/Python-Markdown indentation requirements)
  • Struggle with local development setup

Proposed Solution

Create a CONTRIBUTING.md file that documents:

Project-Specific Standards

  • Markdown formatting requirements

    • 4-space indentation for nested lists (due to Python-Markdown compatibility with MkDocs)
    • Markdownlint configuration and rationale
    • Trailing whitespace and line break standards
  • License format requirements

    • Lowercase license identifiers in YAML frontmatter (e.g., cc0-1.0 not CC0-1.0)
    • Platform-specific requirements for Hugging Face cards
  • Development workflow

    • Local testing with mkdocs serve
    • File organization standards
    • Commit message conventions

Benefits

  • Consistent contribution quality
  • Reduced back-and-forth in PR reviews
  • Clearer onboarding for new contributors
  • Documentation of technical decisions and constraints

Acceptance Criteria

  • Create CONTRIBUTING.md file in repository root
  • Document markdown formatting standards with rationale
  • Include license format requirements
  • Provide local development setup instructions
  • Reference existing tools (markdownlint config, MkDocs)
  • Get review and approval from @egrace479 and @hlapp

This addresses issues identified during the FAIR Guide checklist review and will help maintain consistency as the project grows.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions