Mirror: The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.
Add updated CONTRIBUTING guide
+136
+136
CONTRIBUTING.md
+136
CONTRIBUTING.md
···
1
+
# Development
2
+
3
+
Thanks for contributing! We want to ensure that `urql` evolves and fulfills
4
+
its idea of extensibility and flexibility by seeing continuous improvements
5
+
and enhancements, no matter how small or big they might be.
6
+
7
+
If you're about to add a new exchange, please consider publishing it as
8
+
a separate package.
9
+
10
+
## How to contribute?
11
+
12
+
We follow fairly standard but lenient rules around pull requests and issues.
13
+
Please pick a title that describes your change briefly, optionally in the imperative
14
+
mood if possible.
15
+
16
+
If you have an idea for a feature or want to fix a bug, consider opening an issue
17
+
first. We're also happy to discuss and help you open a PR and get your changes
18
+
in!
19
+
20
+
## How do I set up the project?
21
+
22
+
Luckily it's not hard to get started. You can install dependencies using yarn.
23
+
Please don't use `npm` to respect the lockfile.
24
+
25
+
```sh
26
+
yarn
27
+
```
28
+
29
+
There are multiple commands you can run in the root folder to test your changes:
30
+
31
+
```sh
32
+
# TypeScript checks:
33
+
yarn run check
34
+
35
+
# Linting (prettier & eslint):
36
+
yarn run lint
37
+
38
+
# Jest Tests (for all packages):
39
+
yarn run test
40
+
41
+
# Builds (for all packages):
42
+
yarn run build
43
+
```
44
+
45
+
You can find the main packages in `packages/*` and the addon exchanges in `exchanges/*`.
46
+
Each package also has its own scripts that are common and shared between all packages.
47
+
48
+
```sh
49
+
# Jest Tests for the current package:
50
+
yarn run test
51
+
52
+
# Builds for the current package:
53
+
yarn run build
54
+
55
+
# TypeScript checks for the current package:
56
+
yarn run check
57
+
```
58
+
59
+
While you can run `build` globally in the interest of time it's advisable to only run it
60
+
on the packages you're working on. Note that TypeScript checks don't require any packages
61
+
to be built.
62
+
63
+
## How do I test my changes?
64
+
65
+
It's always good practice to run the tests when making changes. If you're unsure which packages
66
+
may be affected by your new tests or changes you may run `yarn test --watch` in the root of
67
+
the repository.
68
+
69
+
If your editor is not set up with type checks you may also want to run `yarn run check` on your
70
+
changes.
71
+
72
+
Additionally you can head to any example in the `examples/` folder
73
+
and run them. There you'll also need to run `yarn` to install their
74
+
dependencies. All examples are started using `yarn start`.
75
+
76
+
## How do I lint my code?
77
+
78
+
We ensure consistency in `urql`'s codebase using `eslint` and `prettier`.
79
+
They are run on a `precommit` hook, so if something's off they'll try
80
+
to automatically fix up your code, or display an error.
81
+
82
+
If you have them set up in your editor, even better!
83
+
84
+
## How do I upgrade all dependencies?
85
+
86
+
It may be a good idea to keep all dependencies on the `urql` repository up-to-date every now and
87
+
then. Typically we do this by running `yarn upgrade-interactive --latest` and checking one-by-one
88
+
which dependencies will need to be bumped. In case of any security issues it may make sense to
89
+
just run `yarn upgrade [package]`.
90
+
91
+
Afterwards `yarn` may accidentally introduce duplicate packages due to some transitive dependencies
92
+
having been upgraded separately. This can be fixed by running:
93
+
94
+
```sh
95
+
npx yarn-deduplicate yarn.lock
96
+
yarn
97
+
```
98
+
99
+
## How do I add a new package?
100
+
101
+
When adding a new package, start by copying a `package.json` file from another project.
102
+
You may want to alter the following fields first:
103
+
104
+
- `name`
105
+
- `version` (either start at `0.1.0` or `1.0.0`)
106
+
- `description`
107
+
- `repository.directory`
108
+
- `keywords`
109
+
110
+
Make sure to also alter the `devDependencies`, `peerDependencies`, and `dependencies` to match
111
+
the new package's needs.
112
+
113
+
**The `main` and `module` fields follow a convention:**
114
+
All output bundles will always be output in the `./dist` folder by `rollup`, which is set up in
115
+
the `build` script. Their filenames are a "kebab case" (dash-cased) version of the `name` field with
116
+
an appropriate extension (`.esm.js` for `module` and `.cjs.js` for `main`).
117
+
118
+
If your entrypoint won't be at `src/index.ts` you may alter it. But the `types` field has to match
119
+
the same file relative to the `dist/types` folder, where `rollup` will output the TypeScript
120
+
declaration files. When setting up your package make sure to create a `src/index.ts` file (or a file
121
+
at what you've set `source` to)
122
+
123
+
The `scripts.prepare` task is set up to check your new `package.json` file for correctness. So in
124
+
case you get anything wrong, you'll get a short error when running `yarn` after setting your new
125
+
project up. Just in case! 😄
126
+
127
+
Lastly, your new package will need to be added to the `tsconfig.json` in the root of the repository.
128
+
Add a new entry to `compilerOptions.paths` where the key is the `name` you've used in your
129
+
`package.json` and the value is an array with a single entry, the path to your package + `src/`.
130
+
131
+
Afterwards you can check whether everything is working correctly by running:
132
+
133
+
```sh
134
+
yarn
135
+
yarn run check
136
+
```