Mirror: The small sibling of the graphql package, slimmed down for client-side libraries.
kitten.sh
1# Development
2
3Thanks for contributing! We want to ensure that `graphql-web-lite` evolves
4and fulfills its idea of being a drop-in alias replacement to make your
5client-side GraphQL smaller and faster!
6
7## How to contribute?
8
9We follow fairly standard but lenient rules around pull requests and issues.
10Please pick a title that describes your change briefly, optionally in the imperative
11mood if possible.
12
13If you have an idea for a feature or want to fix a bug, consider opening an issue
14first. We're also happy to discuss and help you open a PR and get your changes
15in!
16
17- If you have a question, try [creating a GitHub Discussions thread.](https://github.com/0no-co/graphql-web-lite/discussions/new/choose)
18- If you think you've found a bug, [open a new issue.](https://github.com/0no-co/graphql-web-lite/issues/new)
19- or, if you found a bug you'd like to fix, [open a PR.](https://github.com/0no-co/graphql-web-lite/compare)
20- If you'd like to propose a change [open an RFC issue.](https://github.com/0no-co/graphql-web-lite/issues/new?labels=future+%F0%9F%94%AE&template=RFC.md&title=RFC%3A+Your+Proposal) You can read more about the RFC process [below](#how-do-i-propose-changes).
21
22### What are the issue conventions?
23
24There are **no strict conventions**, but we do have two templates in place that will fit most
25issues, since questions and other discussion start on GitHub Discussions. The bug template is fairly
26standard and the rule of thumb is to try to explain **what you expected** and **what you got
27instead.** Following this makes it very clear whether it's a known behavior, an unexpected issue,
28or an undocumented quirk.
29
30### How do I propose changes?
31
32We follow an **RFC proposal process**. This allows anyone to propose a new feature or a change, and
33allows us to communicate our current planned features or changes, so any technical discussion,
34progress, or upcoming changes are always **documented transparently.** You can [find the RFC
35template](https://github.com/0no-co/graphql-web-lite/issues/new/choose) in our issue creator.
36
37### What are the PR conventions?
38
39This also comes with **no strict conventions**. We only ask you to follow the PR template we have
40in place more strictly here than the templates for issues, since it asks you to list a summary
41(maybe even with a short explanation) and a list of technical changes.
42
43If you're **resolving** an issue please don't forget to add `Resolve #123` to the description so that
44it's automatically linked, so that there's no ambiguity and which issue is being addressed (if any)
45
46You'll find that a comment by the "Changeset" bot may pop up. If you don't know what a **changeset**
47is and why it's asking you to document your changes, read on at ["How do I document a change for the
48changelog"](#how-do-i-document-a-change-for-the-changelog)
49
50We also typically **name** our PRs with a slightly descriptive title, e.g. `feat: Title`.
51
52## How do I set up the project?
53
54Luckily it's not hard to get started. You can install dependencie
55[using `pnpm`](https://pnpm.io/installation#using-corepack).
56Please don't use `npm` or `yarn` to respect the lockfile.
57
58```sh
59pnpm install
60```
61
62There are multiple commands you can run in the root folder to test your changes:
63
64```sh
65# TypeScript checks:
66pnpm run check
67
68# Linting (prettier & eslint):
69pnpm run lint
70
71# Unit Tests:
72pnpm run test
73
74# Builds:
75pnpm run build
76```
77
78## How do I test my changes?
79
80It's always good practice to run the tests when making changes. If you're unsure which packages
81may be affected by your new tests or changes you may run `pnpm test` in the root of
82the repository.
83
84If your editor is not set up with type checks you may also want to run `pnpm run check` on your
85changes.
86
87Additionally you can head to any example in the `examples/` folder
88and run them. There you'll also need to install their dependencies as they're isolated projects,
89without a lockfile and without linking to packages in the monorepos.
90All examples are started using the `package.json`'s `start` script.
91
92## How do I lint my code?
93
94We ensure consistency in this codebase using `eslint` and `prettier`.
95They are run on a `precommit` hook, so if something's off they'll try
96to automatically fix up your code, or display an error.
97
98If you have them set up in your editor, even better!
99
100## How do I document a change for the changelog?
101
102This project uses [changesets](https://github.com/atlassian/changesets). This means that for
103every PR there must be documentation for what has been changed and which package is affected.
104
105You can document a change by running `changeset`, which will ask you which packages
106have changed and whether the change is major/minor/patch. It will then ask you to write
107a change entry as markdown.
108
109```sh
110# In the root of the urql repository call:
111pnpm changeset
112```
113
114This will create a new "changeset file" in the `.changeset` folder, which you should commit and
115push, so that it's added to your PR.
116This will eventually end up in the package's `CHANGELOG.md` file when we do a release.
117
118You won't need to add a changeset if you're simply making "non-visible" changes to the docs or other
119files that aren't published to the npm registry.
120
121[Read more about adding a `changeset` here.](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md#i-am-in-a-multi-package-repository-a-mono-repo)
122
123## How do I release new versions of our packages?
124
125Hold up, that's **automated**! Since we use `changeset` to document our changes, which determines what
126goes into the changelog and what kind of version bump a change should make, you can also use the
127tool to check what's currently posed to change after a release batch using: `pnpm changeset status`.
128
129We have a [GitHub Actions workflow](./.github/workflow/release.yml) which is triggered whenever new
130changes are merged. It will always open a **"Version Packages" PR** which is kept up-to-date. This PR
131documents all changes that are made and will show in its description what all new changelogs are
132going to contain for their new entries.
133
134Once a "Version Packages" PR is approved by a contributor and merged, the action will automatically
135take care of creating the release, publishing all updated packages to the npm registry, and creating
136appropriate tags on GitHub too.
137
138This process is automated, but the changelog should be checked for errors.
139
140As to **when** to merge the automated PR and publish? Maybe not after every change. Typically there
141are two release batches: hotfixes and release batches. We expect that a hotfix for a single package
142should go out as quickly as possible if it negatively affects users. For **release batches**
143however, it's common to assume that if one change is made to a package that more will follow in the
144same week. So waiting for **a day or two** when other changes are expected will make sense to keep the
145fatigue as low as possible for downstream maintainers.
146
147## How do I upgrade all dependencies?
148
149It may be a good idea to keep all dependencies on this repository **up-to-date** every now and
150then. Typically we do this by running `pnpm update --interactive --latest` and checking one-by-one
151which dependencies will need to be bumped. In case of any security issues it may make sense to
152just run `pnpm update [package]`.
153
154While this is rare with `pnpm`, upgrading some transitive dependencies may accidentally duplicate
155them if two packages depend on different compatible version ranges. This can be fixed by running:
156
157```sh
158pnpm dedupe
159pnpm install
160```
161
162It's common to then **create a PR** (with a changeset documenting the packages that need to reflect
163new changes if any `dependencies` have changed) with the name of
164"(chore) - Upgrade direct and transitive dependencies" or something similar.