UNPKG

6.98 kBMarkdownView Raw
1## @changesets/cli 🦋
2
3[![View changelog](https://img.shields.io/badge/changelogs.xyz-Explore%20Changelog-brightgreen)](https://changelogs.xyz/@changesets/cli)
4
5The primary implementation of [changesets](https://github.com/Noviny/changesets). Helps you manage the versioning
6and changelog entries for your packages, with a focus on versioning within a mono-repository (though we support
7single-package repositories too).
8
9This package is intended as a successor to `@atlaskit/build-releases` with a more general focus. It works in
10[bolt](https://www.npmjs.com/package/bolt) multi-package repositories, [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) multi-package repositories, and
11in single-package repositories.
12
13## Getting Started
14
15If you are installing this in a monorepo run
16
17```
18yarn add @changesets/cli
19yarn changeset init
20```
21
22otherwise run
23
24```
25yarn add --dev @changesets/cli
26yarn changeset init
27```
28
29From here you are set up to use changesets. Add your first changeset by running
30
31```
32yarn changeset
33```
34
35and following the prompts that you are presented with.
36
37Below you can find a basic workflow for maintainers to help them use changesets, which you can vary to meet your own needs.
38
39## Core Concepts
40
41The core concept that `changesets` follows is that contributors to a repository should be able to declare an intent to release, and that multiple intents should be able to be combined sensibly. Sensibly here refers to if there is one intent to release button as a 'minor' and another to release button as a 'patch', only one release will be made, at the higher of the two versions.
42
43A single `changeset` is an intent to release stored as data, with the information we need to combine multiple changesets and coordinate releases. It will also update internal dependencies within a multi-package repository.
44
45## Base workflow
46
47Contributor runs:
48
49```
50yarn changeset
51```
52
53or
54
55```
56npx changeset
57```
58
59and answers the provided questions.
60
61When the maintainer wants to release packages, they should run
62
63```
64yarn changeset version
65```
66
67or
68
69```
70npx changeset version
71```
72
73and then
74
75```
76yarn changeset publish
77```
78
79or
80
81```
82npx changeset publish
83```
84
85The commands are explained further below.
86
87## Commands
88
89### init
90
91```
92changeset init
93```
94
95This command sets up the `.changeset` folder. It generates a readme and a config file. The config file includes the default options, as well as comments on what these options represent. You should run this command once, when you are setting up `changesets`.
96
97To publish public packages to NPM, you'll need to edit `.changeset/config.json` and change `"access": "restricted",` to `"access": "public",`. Read more about [access in config file options](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md#access-restricted--public). The `publishConfig` of each `package.json` is also respected and takes a priority over monorepo-wide setting in `.changeset/config.json`.
98
99### add
100
101```
102changeset [--empty] [--open]
103```
104
105or
106
107```
108changeset add [--empty] [--open]
109```
110
111This command will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the entire changeset. At the final step it will show the changeset it will generate, and confirm that you want to add it.
112
113Once confirmed, the changeset will write a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them.
114
115A changeset that major bumps `@changesets/cli` would look like this:
116
117```md
118---
119"@changesets/cli": major
120---
121
122A description of the major changes.
123```
124
125If you want to modify this file after it's generated, that's completely fine or if you want to write changeset files yourself, that's also fine.
126
127- `--empty` - allows you to create an empty changeset if no packages are being bumped, usually only required if you have CI that blocks merges without a changeset.
128
129A changeset created with the `empty` flag would look like this:
130
131```md
132---
133---
134```
135
136If you set the `commit` option in the config, the command will add the updated changeset files and then commit them.
137
138- `--open` - opens the created changeset in an external editor
139
140### version
141
142```
143changeset version
144```
145
146Updates the versions for all packages described in changesets since last release along with any dependents inside the repo that are out of range.
147
148Will also create/append to a CHANGELOG file for each package using the summaries from the changesets.
149
150We recommend making sure changes made from this command are merged back into the base branch before you run `publish`.
151
152This command will read then delete changesets on disk, ensuring that they are only used once.
153
154### publish
155
156```
157changeset publish [--otp={token}]
158```
159
160Publishes to NPM repo, and creates git tags. Because this command assumes that last commit is the release commit you should not commit any changes between calling `version` and `publish`. These commands are separate to enable you to check if release commit is accurate.
161
162- `--otp={token}` - allows you to provide an npm one-time password if you have auth and writes enabled on npm. The CLI also prompts for the OTP if it's not provided with the `--otp` option.
163
164**NOTE:** You will still need to push your changes back to the base branch after this
165
166```
167git push --follow-tags
168```
169
170### status
171
172```
173status [--verbose] [--output={filePath}] [--since={gitTag}]
174```
175
176The status command provides information about the changesets that currently exist. If there are changes to packages but no changesets are present, it exits with error status code `1`.
177
178- `--verbose` - use if you want to know the new versions, and get a link to the relevant changeset summary.
179
180- `--output` - allows you to write the json object of the status out, for consumption by other tools, such as CI.
181
182- `--since` - to only display information about changesets since a specific branch or git tag. While this can be
183 used to add a CI check for changesets, we recommend not doing this. We instead recommend using the [changeset bot](https://github.com/apps/changeset-bot)
184 to detect pull requests missing changesets, as not all pull requests need one.
185
186### pre
187
188```
189pre [exit|enter {tag}]
190```
191
192The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a prerelease, you should run `changeset pre enter next`(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with `changeset version` and `changeset publish`. For more information about the pre command, see [the prereleases documentation](https://github.com/changesets/changesets/blob/main/docs/prereleases.md).
193
194### Bumping peerDependencies
195
196In almost all circumstances, internal packages will be bumped as a patch. The one exception is when the dependency is a `peerDependency`, in which case the change will become a major.