Skip to content

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

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)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions