Maintainer guide
See also Developer guide.
We need you!
Help us develop and maintain Styleguidist:
- Answer questions in GitHub issues and Stack Overflow.
- Review pull requests.
- Fix bugs and add new features.
- Write articles and talk about Styleguidist on conferences and meetups (we’re always happy to review your texts and slides).
Commit message conventions
We use ESLint commit message conventions.
Each commit looks like this:
The Tag
is one of the following:
Fix
— for a bug fix.Update
— for a backwards-compatible enhancement.New
— implemented a new feature.Breaking
— for a backwards—incompatible enhancement or feature.Docs
— changes to documentation only.Build
— changes to build process only.Upgrade
— for a dependency upgrade.Chore
— for refactoring, adding tests and so on (anything that isn’t user-facing).
If the commit doesn’t completely fix the issue, then use (refs #1234
) instead of (fixes #1234
).
Here are some good commit message summary examples:
Pull requests
Maintainers merge pull requests by squashing all commits and editing the commit message if necessary using the GitHub user interface.
Use an appropriate commit type. Be especially careful with breaking changes. See Commit message conventions above for details.
Releases
We’re doing automated releases with semantic-release. We’re using milestones to group approved pull requests that should be released together (most useful for major releases).
Patch releases
Any commit of a Fix
or Update
types merged into the master branch, is published as a patch release as soon as CI passes.
Minor releases
Any commit of a New
type merged into the master branch, is published as a minor release as soon as CI passes.
Major releases
Any commit of a Breaking
type merged into the master branch, is published as a major release as soon as CI passes.
- Merge all pull requests from a milestone. If a milestone has more than one pull request, they should be merged and released together:
- Create a new branch.
- Merge all pull requests into this new branch (you can change the target branch on the pull request page and merge it using the GitHub user interface).
- Resolve possible merge conflicts.
- Wait until semantic-release publishes the release.
- Edit the release notes on GitHub (see Changelogs below).
- Tweet the release!
Changelogs
What is a good changelog
- Changelogs are written for users, not developers.
- Changelog should show new features with code examples or GIFs.
- Changelog should make all breaking changes clear.
- Changelog should explain how to migrate to a new version if there are breaking changes.
- Commit log is not a changelog but can be a base for it.
Here’s a good example of a changelog. Check out Keep a Changelog for more details on good changelogs.
What should be in a changelog
- Information about pull request authors:
(#1040 by @rafaesc)
- Open Collective link at the very top:
👋 **[Support Styleguidist](https://opencollective.com/styleguidist) on Open Collective** 👋