Mirror: The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.
Update CoNTRIBUTING guide
+52
-2
+52
-2
CONTRIBUTING.md
+52
-2
CONTRIBUTING.md
···
160
160
yarn run check
161
161
```
162
162
163
+
## When and how do I add a changeset?
164
+
165
+
Our changelogs and releases are maintained using `changeset`. For each PR that actively changes the
166
+
behaviour of one or more packages in our monorepo it allows you to log the change and classify it
167
+
per package as either `patch`, `minor`, or `major`.
168
+
169
+
You won't need to add a changeset if you're simply making "non-visible" changes to the docs or other
170
+
files that aren't published to `npm`.
171
+
172
+
If you are however making visible changes you can track a change by calling the `changeset` CLI.
173
+
174
+
```sh
175
+
# In the root of the urql repository call:
176
+
yarn changeset
177
+
```
178
+
179
+
This will open an interactive CLI that asks you to track your changes and enter a change message.
180
+
You should always add to the message, what you've changed (not which package if it's only for a
181
+
single package though) and what the impact is. If it's a breaking change it should also include some
182
+
instructions on how users should update their code.
183
+
184
+
This will create a new "changeset file" in the `.changeset` folder, which you should commit and
185
+
push, so that it's added to your PR.
186
+
163
187
## How do I release new versions of our packages?
164
188
165
189
The process of releasing versions is automated using `changeset`. This moves a lot of
···
169
193
170
194
First check what changes you're about to release with `yarn changeset status`.
171
195
172
-
Then the process is similar to using `yarn version` and `yarn publish`:
196
+
Then the process is similar to using `yarn version` and `yarn publish`.
197
+
198
+
First we'll run `yarn changeset version` to bump all packages' versions and update CHANGELOG files:
173
199
174
200
```sh
175
201
# This will automatically bump versions as necessary and update CHANGELOG files:
176
202
yarn changeset version
177
-
# Please check all versions and CHANGELOGs manually.
203
+
```
204
+
205
+
> **Note:** This command requires you to create a [GitHub Personal Access Token](https://github.com/settings/tokens/new)
206
+
> and have it set on the `GITHUB_TOKEN` environment variable, either globally, e.g. in your
207
+
> `~/.profile` file, or locally in a `.env` file.
208
+
209
+
Then verify that the updated `package.json` and `CHANGELOG.md` files look correct and commit the
210
+
changes:
211
+
212
+
```sh
213
+
# Commit all updated files
214
+
git commit -a -m 'Version Packages'
215
+
```
216
+
217
+
At this point we have a new commit with packages that have been updated and should be published.
218
+
Please don't push this commit before publishing so that we keep `master` in a pre-release state, in
219
+
case the publish actually fails!
220
+
221
+
```
178
222
# Then publish all new packages / versions:
179
223
yarn changeset publish
224
+
# And push the "Version Packages" commit and all tags afterwards:
225
+
git push && git push --tags
180
226
```
227
+
228
+
Publishing the packages will also create the tags, it won't however push them automatically. After
229
+
you've pushed the new tags, please make sure to update releases with the new content in each
230
+
`CHANGELOG.md`, like so: https://github.com/FormidableLabs/urql/releases/tag/%40urql%2Fexchange-graphcache%402.2.2