🤝 Reading: Open-Source Contribution Guides

For significant changes only — to align with the project direction first:

The guide says: "For significant changes, open an issue first and wait for maintainer feedback before investing time in implementation. This prevents duplicate work and ensures the change aligns with the project's direction."

The guide gives two clear rules:

• Significant changes → open issue first, wait for feedback, then code
• Small fixes (typos, broken links, 1-3 line bug fixes) → a PR directly is fine

Why maintainers require this:

• A contributor might spend a week implementing a feature that maintainers don't want in the project
• Another contributor might already be working on the same thing (duplicate work)
• The proposed design might conflict with unreleased plans the core team has

Opening an issue is a "cheap signal" — low effort for the contributor, but it prevents expensive wasted work for everyone.

Open-source contribution vocabulary:

• maintainer → someone with commit access who reviews and merges contributions
• contributor → anyone who submits a PR or opens an issue
• duplicate work → two people implementing the same thing independently
• aligns with the project's direction → fits the maintainers' vision and roadmap

"Fixes #1234" links the PR to issue #1234 and auto-closes it on merge:

On GitHub, certain keywords in PR descriptions automatically link to and close issues when the PR is merged:

• Fixes #N — links to issue N, closes it when merged to the default branch
• Closes #N — same behavior
• Resolves #N — same behavior

What actually happens on merge:

1. The PR is merged into main
2. GitHub automatically closes issue #1234
3. The issue timeline shows "Closed by PR #XXX"
4. The PR page shows "Closes issue #1234"

Why this is useful for maintainers:

• No need to manually close issues after merging
• Creates a permanent link between bug-report and fix
• Makes it easy to find which commit/PR fixed a specific issue

CONTRIBUTING.md practice
The guide says: "Reference the issue your PR addresses: 'Fixes #1234' in the PR description." — this is a standard convention in almost every open-source project on GitHub.

chore: — for maintenance and dependency updates:

The guide shows: "chore: upgrade esbuild to v0.19" — a dependency upgrade is a chore.

Conventional Commits prefixes and what they mean:

• feat: → adds user-facing functionality (triggers a MINOR version bump in SemVer)
• fix: → fixes a bug that affected users (triggers a PATCH bump)
• docs: → documentation only — README, API docs, code comments
• chore: → maintenance tasks that don't affect production behavior: dependency updates, build config, CI changes, test infrastructure
• refactor: → code restructuring without behavior change
• test: → adding or fixing tests
• perf: → performance improvement
• ci: → CI/CD pipeline changes
• BREAKING CHANGE: → major change (add to footer, or use feat!:)

Why Conventional Commits help teams:
Automated tools use these prefixes to generate changelogs (like CHANGELOG.md) and to determine the next version number automatically — no manual release notes needed.