Skip to content

Commit c9610e3

Browse files
Re-word everything
1 parent 29c3ef1 commit c9610e3

2 files changed

Lines changed: 11 additions & 13 deletions

File tree

‎docs/command-line-options.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -101,25 +101,25 @@ Snapshot is used for a special kind of publishing for testing - it creates tempo
101101
changeset publish [--otp={token}]
102102
```
103103

104-
This publishes changes to npm, and creates git tags. This works by going into each package, checking if the version it has in its `package.json` is published on npm, and if it is not, running the `npm publish`.
104+
This publishes changes to npm, and creates git tags. The command works by:
105105

106-
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 the releases changes are acurate.
107-
108-
`--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.
106+
- querying current versions in the repository
107+
- comparing the version it has in its `package.json` with published versions
108+
- trying to publish what has not been published yet by running `npm publish`
109109

110-
`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](./snapshot-releases.md).
110+
Importantly, `changeset publish` doesn't care about changeset files at all. If invoked, it will still run through the above actions whether a changeset file has been generated or not.
111111

112-
### Unintended first time publish
112+
This means an accidental publish can happen if you have an unpublished package (or even an unpublished version of a package), start using Changesets (but don't generate a changeset yet), and use our [changesets/action](https://github.com/changesets/action). If you don't immediately add a changeset file then the first run of the action just calls `changeset publish` and it publishes what has not been published yet. Unfortunately, this means something marked with a throwaway version of say `0.0.0` in package.json would still get published.
113113

114-
You might have a GitHub Action set up that does [automatic snapshots on pull requests](./snapshot-releases.md#automatic-snapshots-on-prs). There is an unintended consequence to this with brand new packages that have never been published to npm before.
114+
You are more likely to run into this if you have a GitHub Action set up that does [automatic snapshots on pull requests](./snapshot-releases.md#automatic-snapshots-on-prs), because running `changeset version && changeset publish` sequentially in CI means that `changeset publish` will run regardless if `changeset version` did anything or exited.
115115

116-
`changeset version` and `changeset publish` are decoupled in that no information is shared between them.
116+
You can get around this behavior by temporarily marking `private: true` in package.json while in development, and removing it when you're ready to generate a changeset and publish the package.
117117

118-
`changeset publish` actually doesn't care if a changeset is even generated, it will still publish the version that doesn't exist on npm even if `changeset version` exits because no unreleased changesets were found.
118+
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 the releases changes are acurate.
119119

120-
So, if you have automatic snapshots on PRs set up in the repo, and then create a PR adding a brand new package with a version of `0.0.0` in package.json (common scenario when just starting out, a throwaway version number when still in development), the GitHub Action will run on the PR and `changeset publish` will see that `0.0.0` has not been published on npm for this package, and **it will publish that version.**
120+
`--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.
121121

122-
You can get around this by temporarily marking `private: true` in package.json while setting up the new package, and removing it when you're ready to generate a changeset.
122+
`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](./snapshot-releases.md).
123123

124124
### Git Tags
125125

‎docs/snapshot-releases.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,5 +90,3 @@ jobs:
9090
This will generate a snapshot on each commit to a PR using the commit `SHA`, and publish it under the `prerelease` tag. This is very handy if you need to incrementally test out changes in your PR and don't want to generate snapshots manually for each commit.
9191

9292
There is an **unintended consequence** to this for brand new packages that have never been published to npm before. You can read more about it in the [changeset publish docs](./command-line-options.md#unintended-first-time-publish).
93-
94-
**Please note:** In addition to the repository check (`if: github.repository == ...`), we recommend that you also [turn off workflow runs for forks](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-required-approval-for-workflows-from-public-forks). This will prevent the workflow from running on public forks, unless you approve it.

0 commit comments

Comments
 (0)