Skip to content

Commit 501eabc

Browse files
authored
chore(repo): Add 'why we use changesets' section to contributing guide (clerk#1395)
1 parent aba7c64 commit 501eabc

1 file changed

Lines changed: 7 additions & 1 deletion

File tree

docs/CONTRIBUTING.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ WIP
8787
7. [Open a Pull Request](https://github.com/clerkinc/javascript/compare?expand=1). Make sure the description includes enough information for the reviewer to understand what the PR is about.
8888
8. Follow the instructions of the pull request template
8989

90-
### Changeset
90+
### Changesets
9191

9292
For more details about changesets, see [Adding a Changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).
9393
A changeset is a piece of information about changes made in a branch or commit. It holds three bits of information:
@@ -121,6 +121,12 @@ Tips:
121121
- Changesets are just markdown files. Feel free to add as much markdown as you want to better describe the change.
122122
- Multiple changesets can be added in a single PR if needed, please see [Tips on adding changesets](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md#you-can-add-more-than-one-changeset-to-a-pull-request)
123123

124+
#### Why We Use Changesets
125+
126+
Great release notes and changelogs are an incredibly important trait of good software. We are always working hard at Clerk to bring updates and improvements to our libraries. And while we believe that this is a good thing, it also means we need to be responsible to our users in making clear what these changes are in a way that is as brief, clear, and understandable as possible. We have all seen libraries that publish changelogs as a list of commits, and I don't think many would argue that while this makes it easy for library developers, it's far from ideal for library users. To reach the standards we have for our library users' experience with Clerk, there is nothing that beats hand-written changelogs by the developers who worked on the features, and this is exactly what changesets empowers us to provide.
127+
128+
Changesets provides streamlined tooling and enforcement to ensure that developers working on features have as easy of a time as possible writing great changelogs, and puts together release notes for us at the quality bar that we strive for. Make sure to think from the perspecitve of a user when writing changesets to make it crystal clear what your feature is, what impact is has on the library, how to use it, and how to find more detail, if relevant.
129+
124130
### Commit messages
125131

126132
Even though we don't use commit messages to track changes between releases, all commit messages need to respect the [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.

0 commit comments

Comments
 (0)