Community Building

This reference covers strategies for growing and sustaining an open source community. Load this file only when the user needs detailed guidance on contributor growth, communication channels, events, or sponsorship.

---

The contributor funnel

Every open source project has an implicit funnel that people move through:

Users (thousands)
  -> Issue reporters (hundreds)
    -> First-time contributors (dozens)
      -> Repeat contributors (handful)
        -> Core maintainers (2-5)

Your job as a maintainer is to reduce friction at every stage of this funnel.

Stage 1: User to reporter

• Make it easy to report issues with good templates
• Don't require extensive triage from reporters (they're volunteering their time)
• Respond quickly, even if just to acknowledge the report
• Never be dismissive - "that's not a bug" without explanation drives people away

Stage 2: Reporter to first-time contributor

This is the highest-leverage transition to optimize:

• Label issues good first issue - New contributors search for this label specifically
• Write detailed issue descriptions - Include what needs to change, where the code lives, and links to relevant docs
• Have a working CONTRIBUTING.md - If the dev setup takes more than 5 minutes, you'll lose most newcomers
• Pre-review before PR - Offer to discuss approach in the issue before they write code
• Be patient with PRs - First-time contributors may not know your code style, git workflow, or CI process

Stage 3: First-time to repeat contributor

• Thank contributors publicly (in release notes, README, or a dedicated page)
• Give constructive, encouraging code review - teach, don't criticize
• Follow up after their PR merges: "Thanks for this! Here are similar issues if you're interested..."
• Invite them to discussions about project direction

Stage 4: Repeat contributor to core maintainer

• Gradually increase trust: review rights, then triage rights, then commit rights
• Document the path to maintainership in GOVERNANCE.md
• Have an explicit "invitation" moment - don't assume they know they're welcome
• Set clear expectations about time commitment and responsibilities

---

Communication channels

GitHub Discussions

Best for: project-specific questions, feature proposals, showcases

• Enable GitHub Discussions in repository settings
• Create categories: Q&A, Ideas, Show and Tell, General
• Pin important threads (roadmap, FAQ, getting started)
• Convert actionable discussions to issues

Discord / Slack

Best for: real-time community interaction, quick questions, social bonding

• Create channels: #general, #help, #development, #announcements
• Set up a welcome message with links to docs and contribution guide
• Moderate actively - one toxic interaction can drive away many quiet contributors
• Discord is preferred over Slack for OSS (no message history limits on free tier)

Mailing lists

Best for: formal announcements, governance decisions, large established projects

• Lower barrier than chat (no account needed beyond email)
• Archived and searchable
• Better for async communication across time zones
• Tools: Google Groups, Mailman, Discourse

Blog / Newsletter

Best for: release announcements, tutorials, project updates, community spotlights

• Publish release blog posts for major versions
• Write contributor spotlights to recognize community members
• Share the project roadmap quarterly
• Tools: Dev.to, Hashnode, GitHub Pages, Substack

---

First-time contributor programs

Hacktoberfest

• Annual event in October encouraging open source contributions
• Add the hacktoberfest topic to your repository
• Label issues with hacktoberfest to make them discoverable
• Expect higher volume but lower quality contributions - plan accordingly
• Have extra maintainer capacity available during October

Google Summer of Code (GSoC)

• Paid program for students to work on open source projects
• Apply as an organization in January/February
• Write project ideas with clear scope and mentors
• Students work May-August with mentorship from your team
• Great for larger features that need sustained effort

GitHub's "Up for Grabs" / Good First Issues

• Curate a list of beginner-friendly issues
• Use the good first issue label consistently
• Sites like up-for-grabs.net and goodfirstissue.dev aggregate these

---

Recognition and retention

All Contributors specification

Use the All Contributors bot to recognize all types of contributions, not just code:

• Code, Documentation, Design, Bug reports, Ideas, Reviews, Tests
• Adds a contributors table to your README automatically
• Install via: .all-contributorsrc config and GitHub bot

Release note credits

Mention contributors in release notes:

## Contributors

Thanks to @alice, @bob, and @charlie for their contributions to this release!

Contributor ladder

Define explicit levels of involvement:

Level	Criteria	Privileges
Contributor	Has merged at least one PR	Listed in Contributors
Reviewer	Sustained quality contributions over 3+ months	Can approve PRs
Committer	Deep knowledge of a subsystem, trusted judgment	Direct push access to their area
Maintainer	Holistic project understanding, community leadership	Full repository access, release authority

---

Sponsorship and sustainability

GitHub Sponsors

• Enable GitHub Sponsors on your profile or organization
• Create tiers with clear benefits (logo on README, priority support, etc.)
• Write a compelling FUNDING.yml and sponsor page
• Publicly thank sponsors in release notes

Open Collective

• Transparent funding - all expenses and income are public
• Good for projects with multiple maintainers sharing funds
• Supports recurring and one-time donations
• Fiscal hosts handle taxes and legal structure

Corporate sponsorship

• Reach out to companies that depend on your project
• Offer sponsorship tiers: logo placement, priority issues, consulting hours
• Consider joining a foundation (Linux Foundation, CNCF, Apache) for larger projects
• Some companies fund OSS through programs like the FOSS Contributor Fund

Grants

• NLNet Foundation - European funding for open internet projects
• Sovereign Tech Fund - German government funding for critical OSS infrastructure
• Mozilla MOSS - Grants for projects aligned with Mozilla's mission
• GitHub Accelerator - Annual program with funding and mentorship

---

Avoiding burnout

Maintainer burnout is the number one threat to open source project health.

Set boundaries

• Document your availability (e.g., "I review PRs on weekends, response within 7 days")
• Use GitHub's status feature to indicate when you're away
• It's okay to close your DMs - direct all questions to public channels

Share the load

• Actively recruit co-maintainers - don't wait until you're burned out
• Delegate triage to trusted contributors
• Use bots for repetitive tasks (stale issues, CLA checks, welcome messages)
• Rotate on-call responsibilities among maintainers

Say no gracefully

Templates for common situations:

Feature request you won't implement: "Thanks for the suggestion! This doesn't align with the project's current direction, but you're welcome to maintain it as a plugin/fork."

PR you won't merge: "I appreciate the effort! Unfortunately, this approach doesn't fit our architecture. I'd suggest [alternative approach]. Happy to discuss further in an issue."

Demands for faster response: "This project is maintained by volunteers in our free time. We'll get to this as soon as we can. If this is urgent for your business, consider sponsoring the project."

Governance Models

This reference covers open source governance structures, decision-making processes, and templates for GOVERNANCE.md. Load this file only when the user needs detailed guidance on setting up or evolving project governance.

---

Governance spectrum

Governance models range from centralized to fully distributed:

BDFL -----> Meritocratic -----> Foundation-backed -----> DAO/Cooperative
(1 person)   (earned trust)     (legal entity)          (token/vote-based)

Most projects start at the left and move right as they grow. There is no universally "best" model - the right choice depends on project size, contributor count, and organizational needs.

---

Model 1: BDFL (Benevolent Dictator for Life)

One person makes all final decisions. Other contributors provide input but the BDFL has the last word.

When to use:

• Early-stage projects with 1-3 core contributors
• Projects with a strong creative vision (programming languages, frameworks)
• When speed of decision-making matters more than consensus

Examples: Python (Guido van Rossum, retired), Linux (Linus Torvalds), Vim (Bram Moolenaar)

Strengths:

• Fast decisions, no committee overhead
• Clear accountability
• Consistent vision

Weaknesses:

• Bus factor of 1
• Can become a bottleneck as project grows
• Risk of alienating contributors who disagree with decisions

Template:

# Governance

## Overview

[Project Name] is led by [Your Name] (@handle), who makes all final decisions
about the project's direction, features, and releases.

## Decision Making

- Day-to-day decisions (bug fixes, minor features) are made by any maintainer
- Significant changes (new features, API changes, architectural decisions) require
  approval from the project lead
- Anyone can propose changes by opening an issue or pull request
- The project lead will respond to proposals within [timeframe]

## Maintainers

| Name | GitHub | Area |
|---|---|---|
| [Your Name] | @handle | Project lead, all areas |
| [Name] | @handle | [specific area] |

## Succession

If the project lead is unable to continue, maintainership transfers to
[designated successor or process for choosing one].

---

Model 2: Meritocratic / Consensus-based

Decision-making power is earned through sustained, quality contributions. Decisions are made by consensus among those with earned authority.

When to use:

• Projects with 3-10+ active contributors
• When you want to distribute decision-making to reduce bottlenecks
• Community-driven projects without strong corporate backing

Examples: Apache projects, Node.js, Rust

Strengths:

• Distributes power and responsibility
• Motivates contributors with a path to influence
• More resilient than BDFL (no single point of failure)

Weaknesses:

• Consensus can be slow
• "Merit" can be biased toward certain types of contributions
• Governance process itself requires maintenance

Template:

# Governance

## Roles

### Contributors
Anyone who has had a pull request merged. Contributors are listed in
[CONTRIBUTORS.md](CONTRIBUTORS.md).

### Committers
Contributors who have demonstrated sustained, high-quality contributions
and deep understanding of a project area. Committers can:
- Merge pull requests in their area of ownership
- Triage and label issues
- Vote on project decisions

Committers are nominated by existing committers and approved by lazy
consensus (no objections within 7 days).

### Technical Steering Committee (TSC)
A group of 3-7 committers who make project-wide decisions. The TSC:
- Sets project roadmap and priorities
- Approves architectural changes (via RFC process)
- Manages releases
- Resolves disputes between committers

TSC members are elected annually by committers.

## Decision Making

### Lazy consensus
Most decisions use lazy consensus: a proposal is announced, and if no one
objects within 7 days, it is accepted. This applies to:
- Merging pull requests
- Adding committers
- Minor process changes

### RFC process
Significant changes require a Request for Comments (RFC):
1. Author opens an RFC issue/PR using the template
2. Community discussion period of 14 days minimum
3. TSC reviews and makes a decision
4. Decision is documented in the RFC

RFCs are required for:
- Breaking API changes
- New major features
- Changes to governance or processes
- Deprecation of existing features

### Voting
When lazy consensus fails, the TSC votes. Decisions require a simple majority.
Votes are recorded publicly.

## Code of Conduct

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
The TSC is responsible for enforcement.

---

Model 3: Foundation-backed

A legal entity (foundation) stewards the project. The foundation provides governance structure, legal protection, and often funding.

When to use:

• Large projects with corporate contributors from multiple companies
• Projects that need trademark protection
• When neutral governance is important (no single company controls the project)
• Projects seeking sustainable funding through membership fees

Examples: Kubernetes (CNCF), Node.js (OpenJS), Linux (Linux Foundation)

Major foundations:

• Linux Foundation - Umbrella for many sub-foundations (CNCF, OpenJS, etc.)
• Apache Software Foundation - Strong governance model, incubator program
• CNCF (Cloud Native Computing Foundation) - Cloud-native projects
• OpenJS Foundation - JavaScript ecosystem projects
• Eclipse Foundation - Enterprise Java and IoT projects
• Python Software Foundation - Python language and ecosystem

Strengths:

• Neutral governance - no single company controls the project
• Legal protection for contributors and the project trademark
• Funding through corporate memberships
• Established processes and best practices

Weaknesses:

• Bureaucratic overhead
• Foundation membership fees can be expensive
• Project may lose some autonomy
• Not suitable for small projects

Template:

# Governance

## Overview

[Project Name] is a project of the [Foundation Name]. The foundation provides
legal, financial, and governance support.

## Governing Board

The Governing Board oversees the project's strategic direction:
- 2 seats appointed by the foundation
- 3 seats elected by committers
- 1 seat for the Technical Lead

The board meets monthly. Minutes are published within 7 days.

## Technical Oversight Committee (TOC)

The TOC makes technical decisions:
- Reviews and approves architectural proposals
- Manages the release process
- Oversees sub-projects and working groups
- Resolves technical disputes

TOC members are elected by active committers for 2-year terms.

## Working Groups

Working groups focus on specific areas:
- **Core** - Runtime, API, and core functionality
- **Documentation** - Docs, tutorials, and examples
- **Ecosystem** - Plugins, integrations, and tooling
- **Security** - Vulnerability management and security reviews

Anyone can participate in working groups. Each WG has 1-2 leads
appointed by the TOC.

## Intellectual Property

All contributions are made under the [license]. Contributors sign
the [Foundation] CLA before their first contribution.

---

RFC (Request for Comments) process

An RFC process is essential for any project beyond the BDFL stage:

RFC template

# RFC: [Title]

## Summary
One paragraph explanation of the proposed change.

## Motivation
Why are we doing this? What problem does it solve?

## Detailed Design
Technical details of how this will be implemented.

## Drawbacks
Why should we NOT do this? What are the risks?

## Alternatives
What other approaches were considered? Why were they rejected?

## Unresolved Questions
What aspects of the design are still TBD?

RFC lifecycle

1. Draft - Author creates RFC as a PR or issue
2. Discussion - Minimum 14-day comment period
3. Final Comment Period (FCP) - 7 days of last call before decision
4. Accepted / Rejected / Postponed - Decision recorded with rationale
5. Implemented - Linked to implementing PRs

---

Conflict resolution

Every governance model needs a conflict resolution process:

1. Discussion - Attempt to resolve through open discussion on the issue/PR
2. Mediation - A neutral maintainer facilitates a resolution
3. Vote - If mediation fails, the TSC/governing body votes
4. Escalation - For code of conduct violations, follow the CoC enforcement process

Code of Conduct enforcement

Adopt the Contributor Covenant and define enforcement:

Violation	Response
First minor offense	Private warning with explanation
Repeated minor offense	Temporary ban from community spaces (7-30 days)
Serious offense	Permanent ban, PR/issue privileges revoked
Threat of violence or harassment	Immediate permanent ban

Enforcement decisions are made by the CoC committee (at least 2 people) and documented privately.

---

Transitioning governance models

BDFL to Meritocratic

This transition usually happens when the BDFL wants to step back:

1. Identify 2-3 trusted contributors for a proto-TSC
2. Write GOVERNANCE.md documenting the new process
3. Run both models in parallel for 3-6 months
4. BDFL gradually delegates decisions to the TSC
5. Formally announce the transition

Meritocratic to Foundation

This usually happens when corporate interest grows:

1. Evaluate foundations that align with your project's ecosystem
2. Apply to the foundation's project intake/incubation process
3. Transfer trademark and assets to the foundation
4. Adopt the foundation's CLA and governance requirements
5. Announce to community with clear explanation of what changes and what stays the same

Licensing Guide

This reference covers open source license selection, compatibility, and strategy in depth. Load this file only when the user needs detailed licensing guidance beyond the quick comparison table in the main SKILL.md.

---

License families

Open source licenses fall into two broad families:

Permissive licenses

Permissive licenses allow users to do almost anything with the code, including using it in proprietary software, as long as they include the original copyright notice.

MIT License

• The most popular open source license
• Short (about 170 words), easy to understand
• Requires: copyright notice in copies
• Allows: commercial use, modification, distribution, private use
• Does NOT require: sharing modifications, patent grant
• Best for: libraries, tools, and projects seeking maximum adoption

Apache License 2.0

• Permissive like MIT but with explicit patent protections
• Requires: copyright notice, state changes, include license text
• Includes: explicit patent grant from contributors
• Includes: patent retaliation clause (if you sue for patent infringement, you lose your license)
• Best for: projects where patent concerns matter (enterprise, cloud, hardware-adjacent)

BSD 2-Clause and 3-Clause

• Functionally similar to MIT
• 3-Clause adds a "no endorsement" clause (can't use project name to promote derivatives)
• Less common than MIT for new projects but still widely used

ISC License

• Functionally equivalent to MIT but even shorter
• Preferred by some projects (e.g., OpenBSD ecosystem) for its brevity

Copyleft licenses

Copyleft licenses require that derivative works also be distributed under the same (or compatible) license. This ensures modifications stay open source.

GNU General Public License v3 (GPL-3.0)

• Strong copyleft: any software that includes GPL code must also be GPL
• "Linking" GPL code into a program makes the whole program GPL
• Includes patent grant and anti-Tivoization provisions
• Best for: projects that want to ensure all derivatives remain open source
• Caution: many companies have policies against using GPL dependencies

GNU Lesser General Public License v3 (LGPL-3.0)

• Weak copyleft: modifications to the LGPL library must be shared, but programs that merely link to it (use it as a dependency) do not need to be LGPL
• Best for: libraries that want copyleft for the library code but permissive linking
• Common in: C/C++ libraries (glibc, Qt)

GNU Affero General Public License v3 (AGPL-3.0)

• Like GPL but closes the "SaaS loophole" - if you run modified AGPL software as a network service, you must make the source available to users of that service
• Best for: server-side software that you want to keep open (databases, web apps)
• Used by: MongoDB (before SSPL), Mastodon, Nextcloud

Mozilla Public License 2.0 (MPL-2.0)

• File-level copyleft: modifications to MPL files must be shared, but new files in the same project can use any license
• A middle ground between permissive and strong copyleft
• Best for: projects wanting copyleft with less friction than GPL

---

License compatibility matrix

When combining code from different licenses, compatibility determines what the combined work's license must be:

License A	License B	Compatible?	Combined license
MIT	MIT	Yes	MIT
MIT	Apache 2.0	Yes	Apache 2.0
MIT	GPL 3.0	Yes	GPL 3.0 (copyleft absorbs permissive)
Apache 2.0	GPL 3.0	Yes	GPL 3.0
Apache 2.0	GPL 2.0 only	No	Incompatible (patent clause conflict)
GPL 3.0	AGPL 3.0	Yes	AGPL 3.0
GPL 2.0	GPL 3.0	Only if "or later"	GPL 3.0 (if "GPL 2.0 or later")
MIT	LGPL 3.0	Yes	LGPL 3.0 for the library, MIT for the rest
MPL 2.0	GPL 3.0	Yes	GPL 3.0
MPL 2.0	Apache 2.0	Yes	Either at file level

Key rule: Permissive licenses are compatible with everything. Copyleft licenses absorb permissive ones. Two different copyleft licenses are usually incompatible unless one explicitly allows it.

---

Dual licensing strategies

Dual licensing means releasing the same code under two licenses simultaneously. Users choose which license to accept.

Open core / Commercial dual license

• Release under AGPL (or GPL) for open source use
• Sell a commercial license for companies that don't want copyleft obligations
• Examples: MySQL (GPL + commercial), MongoDB (originally AGPL + commercial)
• Requires: owning all copyright (CLA needed from contributors)

Permissive + Copyleft dual license

• Release under both MIT and GPL
• Users who want permissive terms use MIT; users who want copyleft protections use GPL
• Less common; mainly used for ecosystem flexibility

CLA requirements for dual licensing

• If you plan to dual license, you MUST have a Contributor License Agreement (CLA) or copyright assignment from all contributors
• Without CLA: each contributor owns their copyright and you cannot relicense their work
• Tools: CLA Assistant (GitHub App), DCO (Developer Certificate of Origin) as lighter alternative

---

Common licensing decisions

"I want maximum adoption"

Use MIT. It's the most recognized, shortest to read, and has no conditions that scare away corporate legal teams.

"I want patent protection"

Use Apache 2.0. The explicit patent grant protects both you and your users.

"I want to prevent proprietary forks"

Use GPL-3.0 for applications or LGPL-3.0 for libraries. Code modifications must be shared under the same terms.

"I'm building a SaaS product and want to stay open"

Use AGPL-3.0. It requires source distribution even when the software is only offered as a service, not distributed as a binary.

"I want copyleft but without the GPL stigma"

Use MPL-2.0. File-level copyleft is less invasive and better understood by corporate legal teams than GPL.

"I want to place code in the public domain"

Use Unlicense or CC0. Note that "public domain" is not a legal concept in all jurisdictions, so these licenses provide a fallback permissive grant.

---

Server Side Public License (SSPL) and similar

The SSPL (created by MongoDB) is NOT considered open source by the OSI. It requires that anyone offering the software as a service must open source their entire service stack. This goes beyond AGPL's requirements.

Other non-OSI licenses to be aware of:

• Business Source License (BSL/BUSL) - Source available, converts to open source after a time delay
• Elastic License 2.0 - Permissive-like but prohibits offering as a managed service
• Commons Clause - Addon that restricts selling the software

These are "source available" licenses, not open source licenses. Do not describe them as open source when advising users.

---

Changing licenses

Changing an established project's license is one of the most complex operations in OSS:

1. You must have copyright over ALL code - either through CLA or by being the sole author
2. Contributions without a CLA are owned by their contributors - you cannot relicense them
3. Options when you don't own all copyright:
   • Get written consent from every contributor
   • Rewrite the contributed code from scratch
   • Fork from a point before the contribution you can't relicense
4. Always announce license changes well in advance and explain the reasoning
5. Previous versions remain under the old license - you can only change going forward

Semantic Versioning and Release Management

This reference covers SemVer edge cases, pre-release conventions, and release automation tooling. Load this file only when the user needs detailed versioning or release guidance.

---

Semantic versioning rules

SemVer follows the format: MAJOR.MINOR.PATCH

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes (breaking changes)
• MINOR version when you add functionality in a backward-compatible manner
• PATCH version when you make backward-compatible bug fixes

What counts as a breaking change?

Change	Breaking?	Bump
Remove a public function or method	Yes	MAJOR
Rename a public function or method	Yes	MAJOR
Change function signature (add required parameter)	Yes	MAJOR
Change return type of a public function	Yes	MAJOR
Change default behavior that users depend on	Yes	MAJOR
Add a new optional parameter with a default	No	MINOR
Add a new public function or method	No	MINOR
Add a new event or hook	No	MINOR
Fix a bug without changing the API	No	PATCH
Improve performance without changing behavior	No	PATCH
Update documentation	No	PATCH
Internal refactoring with no API change	No	PATCH
Add a new dependency	Depends	MINOR (if no API change)
Upgrade a dependency with breaking changes	Maybe	MAJOR if it leaks through your API

Edge cases and judgment calls

Bug fix that changes behavior: If the previous behavior was clearly a bug (not matching docs), fixing it is a PATCH even though some users may depend on the buggy behavior. Document the fix prominently in release notes.

Deprecation: Deprecating a feature is MINOR (it's backward compatible). Removing the deprecated feature is MAJOR. Always give at least one MINOR release cycle between deprecation and removal.

Security fix that changes API: If a security vulnerability requires a breaking change to fix, release it as MAJOR with a clear security advisory. If you can fix it without breaking the API, it's a PATCH.

Pre-1.0 versions (0.x.y): The SemVer spec says anything goes before 1.0.0. In practice, most projects treat 0.MINOR as the "major" and 0.MINOR.PATCH as the "minor." Ship 1.0.0 when you have a stable public API.

---

Pre-release and build metadata

Pre-release versions

Pre-release versions indicate that the version is unstable and might not satisfy the intended compatibility requirements:

1.0.0-alpha.1    # First alpha - feature incomplete, expect breakage
1.0.0-alpha.2    # Second alpha
1.0.0-beta.1     # Feature complete, fixing bugs
1.0.0-beta.2     # More bug fixes
1.0.0-rc.1       # Release candidate - believed ready, final testing
1.0.0-rc.2       # Another release candidate if issues found
1.0.0            # Stable release

Pre-release versions have lower precedence than the associated normal version: 1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0

Build metadata

Build metadata is appended with a + sign and is ignored for version precedence:

1.0.0+build.123
1.0.0+20250301
1.0.0-beta.1+exp.sha.a1b2c3d

Build metadata is informational only - two versions differing only in build metadata are considered equal.

---

Release automation tools

semantic-release (JavaScript ecosystem)

Fully automated version management and package publishing:

• Analyzes commit messages to determine the version bump
• Generates release notes from commit messages
• Publishes to npm and creates GitHub releases
• Requires Conventional Commits format

{
  "release": {
    "branches": ["main"],
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      "@semantic-release/changelog",
      "@semantic-release/npm",
      "@semantic-release/github",
      "@semantic-release/git"
    ]
  }
}

release-please (Google, multi-language)

Creates release PRs automatically based on Conventional Commits:

• Opens a PR that tracks unreleased changes
• Updates CHANGELOG.md and version files
• Merging the PR triggers the release
• Supports: Node.js, Python, Java, Go, Rust, Ruby, and more

# .github/workflows/release-please.yml
on:
  push:
    branches: [main]
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: node

changesets (multi-package / monorepo)

Designed for monorepos with multiple packages:

• Contributors add "changeset" files describing their changes
• A CI job aggregates changesets into version bumps and changelog entries
• Handles inter-package dependency updates automatically
• Used by: Vercel, Chakra UI, Radix

npx changeset        # Create a changeset
npx changeset version # Apply changesets to bump versions
npx changeset publish # Publish to npm

conventional-changelog (standalone)

Generates changelogs from Conventional Commits without full release automation:

npx conventional-changelog -p angular -i CHANGELOG.md -s

---

Conventional Commits

Conventional Commits is a commit message convention that works with all the release automation tools above:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types that affect versioning:

• fix: - triggers a PATCH bump
• feat: - triggers a MINOR bump
• feat!: or any type with BREAKING CHANGE: footer - triggers a MAJOR bump

Common types:

• fix: - Bug fix
• feat: - New feature
• docs: - Documentation only
• style: - Formatting, no code change
• refactor: - Code restructuring, no behavior change
• perf: - Performance improvement
• test: - Adding or fixing tests
• ci: - CI/CD changes
• chore: - Maintenance tasks

Example:

feat(auth): add OAuth 2.0 support for GitHub login

Implements the OAuth 2.0 authorization code flow for GitHub.
Users can now sign in with their GitHub account.

Closes #234

---

Release checklist

For any release, follow this sequence:

1. Freeze - Stop merging new features. Only bug fixes from here.
2. Version - Determine the version bump from changes since last release.
3. Changelog - Write or generate the changelog. Review for accuracy.
4. Test - Run the full test suite. Run manual smoke tests if applicable.
5. Tag - Create an annotated git tag: git tag -a v1.2.0 -m "Release v1.2.0"
6. Build - Create distributable artifacts (if applicable).
7. Publish - Push to package registry (npm, PyPI, crates.io, etc.).
8. Release - Create GitHub Release with changelog as body.
9. Announce - Post to community channels (Discord, blog, Twitter/X, mailing list).
10. Monitor - Watch for regression reports in the first 24-48 hours.

---

Hotfix process

When a critical bug is found in a release:

1. Create a hotfix branch from the release tag: git checkout -b hotfix/1.2.1 v1.2.0
2. Fix the bug with minimal changes (no feature work)
3. Bump PATCH version
4. Follow the full release checklist above
5. Merge the fix back into main to prevent regression