Skip to content

Expand CONTRIBUTING.md with dev environment setup, commit message standards, and PR guidelines #199

@Rama542

Description

@Rama542

Summary

The current CONTRIBUTING.md is minimal and leaves new contributors without
practical guidance to get started confidently. While it mentions running
make verify and make test before submitting a PR, it lacks the foundational
details that reduce friction for first-time contributors.

What's Currently Missing

1. Development Environment Setup

  • No prerequisites listed (Go version, kubectl, required tools)
  • No steps to clone, build, or run the project locally
  • No mention of IDE recommendations or editor config

2. Commit Message Standards

  • The doc says to write "good commit messages" but provides no format or examples
  • No mention of conventional commits, scope conventions, or subject line length limits
  • Example of expected format would help (e.g., fix(scheduler): correct replica count overflow)

3. PR Checklist and Template

  • No PR checklist for contributors to self-review before submitting
  • No guidance on PR size (when to split a large PR)
  • No mention of linking related issues in the PR description

4. Review Timeline Expectations

  • Contributors have no idea how long to wait before following up
  • No SLA or approximate timeline mentioned for first review or approval

5. Testing Requirements

  • make test is mentioned but there's no guidance on what tests to write
  • No direction on unit vs. integration tests, or coverage expectations

Suggested Improvement

Expand CONTRIBUTING.md (or add a linked docs/contributing/ subfolder) to include:

  • Prerequisites and local setup steps
  • Commit message format with examples
  • PR checklist template
  • Review response timeline guidance
  • Testing expectations and examples

Why This Matters

A clear, practical contributing guide directly lowers the barrier for new
contributors. Many open-source contributors abandon their first PR attempt due
to uncertainty — not lack of skill. Improving this document aligns with
Karmada's stated goal of being "a community project driven by its community."

References

  • Current file: CONTRIBUTING.md
  • Related: community-membership.md (references contribution history for
    membership tiers — clearer contribution steps help candidates meet those
    requirements too)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions