commit 1803a486d6d2712f4831990dcdb2dd9fafd10ecd · kitten.sh/graphql.web

.github/FUNDING.yml

···

       1
       1
       +
       github: urql-graphql

     

       2
       2
       +
       open_collective: urql-graphql

+42

.github/ISSUE_TEMPLATE/RFC.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       name: 'RFC'

     

       3
       3
       +
       about: Propose an enhancement / feature and start a discussion

     

       4
       4
       +
       title: 'RFC: Your Proposal'

     

       5
       5
       +
       labels: "future \U0001F52E"

     

       6
       6
       +
       ---

     

       7
       7
       +
       

     

       8
       8
       +
       <!--

     

       9
       9
       +
         🚨 RFCs are for proposed changes (not bugs or questions)

     

       10
       10
       +
         Specifically they are whenever you'd like to see new features

     

       11
       11
       +
         being added, or enable new use-cases.

     

       12
       12
       +
       

     

       13
       13
       +
         Please open a Bug Report for issues/bugs, and use GitHub Discussions

     

       14
       14
       +
         or the Discord channel for questions instead.

     

       15
       15
       +
       -->

     

       16
       16
       +
       

     

       17
       17
       +
       ## Summary

     

       18
       18
       +
       

     

       19
       19
       +
       <!--

     

       20
       20
       +
         Describe in a couple of words *what* you're proposing.

     

       21
       21
       +
         If relevant, include *why* this should be addressed now.

     

       22
       22
       +
         The problem should be clearly stated and the solution

     

       23
       23
       +
         should be summarised.

     

       24
       24
       +
       -->

     

       25
       25
       +
       

     

       26
       26
       +
       ## Proposed Solution

     

       27
       27
       +
       

     

       28
       28
       +
       <!--

     

       29
       29
       +
         Explain the solution you're proposing in detail.

     

       30
       30
       +
         *How* will this change be implemented, and how does it work?

     

       31
       31
       +
       -->

     

       32
       32
       +
       

     

       33
       33
       +
       ## Requirements

     

       34
       34
       +
       

     

       35
       35
       +
       <!--

     

       36
       36
       +
         This section is *optional*.

     

       37
       37
       +
         But if your proposed solution has multiple ways

     

       38
       38
       +
         of being implemented, you don't want to state how

     

       39
       39
       +
         it may be implemented, or you don't know yet how

     

       40
       40
       +
         it will be implemented, then:

     

       41
       41
       +
         *List* what the implementation needs to achieve to fulfil this RFC;

     

       42
       42
       +
       -->

+46

.github/ISSUE_TEMPLATE/bug_report.yaml

···

       1
       1
       +
       name: "\U0001F41E Bug report"

     

       2
       2
       +
       description: Report an issue with graphql.web

     

       3
       3
       +
       labels: []

     

       4
       4
       +
       body:

     

       5
       5
       +
         - type: markdown

     

       6
       6
       +
           attributes:

     

       7
       7
       +
             value: |

     

       8
       8
       +
               Thanks for taking the time to fill out this bug report!

     

       9
       9
       +
         - type: markdown

     

       10
       10
       +
           attributes:

     

       11
       11
       +
             value: |

     

       12
       12
       +
               Thanks for taking the time to fill out this bug report!

     

       13
       13
       +
         - type: textarea

     

       14
       14
       +
           id: bug-description

     

       15
       15
       +
           attributes:

     

       16
       16
       +
             label: Describe the bug

     

       17
       17
       +
             description: Please describe your bug clearly and concisely.

     

       18
       18
       +
             placeholder: Bug description

     

       19
       19
       +
           validations:

     

       20
       20
       +
             required: true

     

       21
       21
       +
         - type: input

     

       22
       22
       +
           id: reproduction

     

       23
       23
       +
           attributes:

     

       24
       24
       +
             label: Reproduction

     

       25
       25
       +
             description: Please provide a reproduction link, e.g. to a sandbox

     

       26
       26
       +
             placeholder: Reproduction

     

       27
       27
       +
           validations:

     

       28
       28
       +
             required: true

     

       29
       29
       +
         - type: textarea

     

       30
       30
       +
           id: version

     

       31
       31
       +
           attributes:

     

       32
       32
       +
             label: Package version

     

       33
       33
       +
             description: The versions of the relevant urql packages you are using

     

       34
       34
       +
             placeholder: "@0no-co/graphql.web@0.1.0"

     

       35
       35
       +
           validations:

     

       36
       36
       +
             required: true

     

       37
       37
       +
         - type: checkboxes

     

       38
       38
       +
           id: checkboxes

     

       39
       39
       +
           attributes:

     

       40
       40
       +
             label: Validations

     

       41
       41
       +
             description: Before submitting the issue, please make sure you do the following

     

       42
       42
       +
             options:

     

       43
       43
       +
               - label: I can confirm that this is a bug report, and not a feature request, RFC, question, or discussion, for which GitHub Discussions should be used

     

       44
       44
       +
                 required: true

     

       45
       45
       +
               - label: Follow our [Code of Conduct](https://github.com/0no-co/graphql.web/blob/main/CODE_OF_CONDUCT.md)

     

       46
       46
       +
                 required: true

.github/ISSUE_TEMPLATE/config.yml

···

       1
       1
       +
       blank_issues_enabled: true

     

       2
       2
       +
       contact_links:

     

       3
       3
       +
         - name: Ask a question

     

       4
       4
       +
           url: https://github.com/0no-co/graphql.web/discussions

     

       5
       5
       +
           about: Ask questions and discuss with other community members

     

       6
       6
       +
         - name: Join the Discord

     

       7
       7
       +
           url: https://discord.gg/Hw8FR8qKfC

     

       8
       8
       +
           about: Chat with maintainers and other community members

+22

.github/PULL_REQUEST_TEMPLATE.md

···

       1
       1
       +
       <!--

     

       2
       2
       +
         Thanks for opening a pull request! We appreciate your dedication and help!

     

       3
       3
       +
         Before submitting your pull request, please make sure to read our CONTRIBUTING guide.

     

       4
       4
       +
       

     

       5
       5
       +
         The best contribution is always a PR, but please make sure to open an issue or discuss

     

       6
       6
       +
         your changes first, if you’re looking to submit a larger PR.

     

       7
       7
       +
       

     

       8
       8
       +
         If this PR is already related to an issue, please reference it like so:

     

       9
       9
       +
         Resolves #123

     

       10
       10
       +
       -->

     

       11
       11
       +
       

     

       12
       12
       +
       ## Summary

     

       13
       13
       +
       

     

       14
       14
       +
       <!-- What's the motivation of this change? What does it solve? -->

     

       15
       15
       +
       

     

       16
       16
       +
       ## Set of changes

     

       17
       17
       +
       

     

       18
       18
       +
       <!--

     

       19
       19
       +
         Roughly list the changes you've made and which packages are affected.

     

       20
       20
       +
         Leave some notes on what may be noteworthy files you've changed.

     

       21
       21
       +
         And lastly, please let us know if you think this is a breaking change.

     

       22
       22
       +
       -->

+163

CONTRIBUTING.md

···

       1
       1
       +
       # Development

     

       2
       2
       +
       

     

       3
       3
       +
       Thanks for contributing! We want to ensure that `@0no-co/graphql-web` evolves

     

       4
       4
       +
       and fulfills its idea of making client-side GraphQL smaller and faster!

     

       5
       5
       +
       

     

       6
       6
       +
       ## How to contribute?

     

       7
       7
       +
       

     

       8
       8
       +
       We follow fairly standard but lenient rules around pull requests and issues.

     

       9
       9
       +
       Please pick a title that describes your change briefly, optionally in the imperative

     

       10
       10
       +
       mood if possible.

     

       11
       11
       +
       

     

       12
       12
       +
       If you have an idea for a feature or want to fix a bug, consider opening an issue

     

       13
       13
       +
       first. We're also happy to discuss and help you open a PR and get your changes

     

       14
       14
       +
       in!

     

       15
       15
       +
       

     

       16
       16
       +
       - If you have a question, try [creating a GitHub Discussions thread.](https://github.com/0no-co/graphql.web/discussions/new/choose)

     

       17
       17
       +
       - If you think you've found a bug, [open a new issue.](https://github.com/0no-co/graphql.web/issues/new)

     

       18
       18
       +
       - or, if you found a bug you'd like to fix, [open a PR.](https://github.com/0no-co/graphql.web/compare)

     

       19
       19
       +
       - If you'd like to propose a change [open an RFC issue.](https://github.com/0no-co/graphql.web/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).

     

       20
       20
       +
       

     

       21
       21
       +
       ### What are the issue conventions?

     

       22
       22
       +
       

     

       23
       23
       +
       There are **no strict conventions**, but we do have two templates in place that will fit most

     

       24
       24
       +
       issues, since questions and other discussion start on GitHub Discussions. The bug template is fairly

     

       25
       25
       +
       standard and the rule of thumb is to try to explain **what you expected** and **what you got

     

       26
       26
       +
       instead.** Following this makes it very clear whether it's a known behavior, an unexpected issue,

     

       27
       27
       +
       or an undocumented quirk.

     

       28
       28
       +
       

     

       29
       29
       +
       ### How do I propose changes?

     

       30
       30
       +
       

     

       31
       31
       +
       We follow an **RFC proposal process**. This allows anyone to propose a new feature or a change, and

     

       32
       32
       +
       allows us to communicate our current planned features or changes, so any technical discussion,

     

       33
       33
       +
       progress, or upcoming changes are always **documented transparently.** You can [find the RFC

     

       34
       34
       +
       template](https://github.com/0no-co/graphql.web/issues/new/choose) in our issue creator.

     

       35
       35
       +
       

     

       36
       36
       +
       ### What are the PR conventions?

     

       37
       37
       +
       

     

       38
       38
       +
       This also comes with **no strict conventions**. We only ask you to follow the PR template we have

     

       39
       39
       +
       in place more strictly here than the templates for issues, since it asks you to list a summary

     

       40
       40
       +
       (maybe even with a short explanation) and a list of technical changes.

     

       41
       41
       +
       

     

       42
       42
       +
       If you're **resolving** an issue please don't forget to add `Resolve #123` to the description so that

     

       43
       43
       +
       it's automatically linked, so that there's no ambiguity and which issue is being addressed (if any)

     

       44
       44
       +
       

     

       45
       45
       +
       You'll find that a comment by the "Changeset" bot may pop up. If you don't know what a **changeset**

     

       46
       46
       +
       is and why it's asking you to document your changes, read on at ["How do I document a change for the

     

       47
       47
       +
       changelog"](#how-do-i-document-a-change-for-the-changelog)

     

       48
       48
       +
       

     

       49
       49
       +
       We also typically **name** our PRs with a slightly descriptive title, e.g. `feat: Title`.

     

       50
       50
       +
       

     

       51
       51
       +
       ## How do I set up the project?

     

       52
       52
       +
       

     

       53
       53
       +
       Luckily it's not hard to get started. You can install dependencie

     

       54
       54
       +
       [using `pnpm`](https://pnpm.io/installation#using-corepack).

     

       55
       55
       +
       Please don't use `npm` or `yarn` to respect the lockfile.

     

       56
       56
       +
       

     

       57
       57
       +
       ```sh

     

       58
       58
       +
       pnpm install

     

       59
       59
       +
       ```

     

       60
       60
       +
       

     

       61
       61
       +
       There are multiple commands you can run in the root folder to test your changes:

     

       62
       62
       +
       

     

       63
       63
       +
       ```sh

     

       64
       64
       +
       # TypeScript checks:

     

       65
       65
       +
       pnpm run check

     

       66
       66
       +
       

     

       67
       67
       +
       # Linting (prettier & eslint):

     

       68
       68
       +
       pnpm run lint

     

       69
       69
       +
       

     

       70
       70
       +
       # Unit Tests:

     

       71
       71
       +
       pnpm run test

     

       72
       72
       +
       

     

       73
       73
       +
       # Builds:

     

       74
       74
       +
       pnpm run build

     

       75
       75
       +
       ```

     

       76
       76
       +
       

     

       77
       77
       +
       ## How do I test my changes?

     

       78
       78
       +
       

     

       79
       79
       +
       It's always good practice to run the tests when making changes. If you're unsure which packages

     

       80
       80
       +
       may be affected by your new tests or changes you may run `pnpm test` in the root of

     

       81
       81
       +
       the repository.

     

       82
       82
       +
       

     

       83
       83
       +
       If your editor is not set up with type checks you may also want to run `pnpm run check` on your

     

       84
       84
       +
       changes.

     

       85
       85
       +
       

     

       86
       86
       +
       Additionally you can head to any example in the `examples/` folder

     

       87
       87
       +
       and run them. There you'll also need to install their dependencies as they're isolated projects,

     

       88
       88
       +
       without a lockfile and without linking to packages in the monorepos.

     

       89
       89
       +
       All examples are started using the `package.json`'s `start` script.

     

       90
       90
       +
       

     

       91
       91
       +
       ## How do I lint my code?

     

       92
       92
       +
       

     

       93
       93
       +
       We ensure consistency in this codebase using `eslint` and `prettier`.

     

       94
       94
       +
       They are run on a `precommit` hook, so if something's off they'll try

     

       95
       95
       +
       to automatically fix up your code, or display an error.

     

       96
       96
       +
       

     

       97
       97
       +
       If you have them set up in your editor, even better!

     

       98
       98
       +
       

     

       99
       99
       +
       ## How do I document a change for the changelog?

     

       100
       100
       +
       

     

       101
       101
       +
       This project uses [changesets](https://github.com/atlassian/changesets). This means that for

     

       102
       102
       +
       every PR there must be documentation for what has been changed and which package is affected.

     

       103
       103
       +
       

     

       104
       104
       +
       You can document a change by running `changeset`, which will ask you which packages

     

       105
       105
       +
       have changed and whether the change is major/minor/patch. It will then ask you to write

     

       106
       106
       +
       a change entry as markdown.

     

       107
       107
       +
       

     

       108
       108
       +
       ```sh

     

       109
       109
       +
       # In the root of the urql repository call:

     

       110
       110
       +
       pnpm changeset

     

       111
       111
       +
       ```

     

       112
       112
       +
       

     

       113
       113
       +
       This will create a new "changeset file" in the `.changeset` folder, which you should commit and

     

       114
       114
       +
       push, so that it's added to your PR.

     

       115
       115
       +
       This will eventually end up in the package's `CHANGELOG.md` file when we do a release.

     

       116
       116
       +
       

     

       117
       117
       +
       You won't need to add a changeset if you're simply making "non-visible" changes to the docs or other

     

       118
       118
       +
       files that aren't published to the npm registry.

     

       119
       119
       +
       

     

       120
       120
       +
       [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)

     

       121
       121
       +
       

     

       122
       122
       +
       ## How do I release new versions of our packages?

     

       123
       123
       +
       

     

       124
       124
       +
       Hold up, that's **automated**! Since we use `changeset` to document our changes, which determines what

     

       125
       125
       +
       goes into the changelog and what kind of version bump a change should make, you can also use the

     

       126
       126
       +
       tool to check what's currently posed to change after a release batch using: `pnpm changeset status`.

     

       127
       127
       +
       

     

       128
       128
       +
       We have a [GitHub Actions workflow](./.github/workflow/release.yml) which is triggered whenever new

     

       129
       129
       +
       changes are merged. It will always open a **"Version Packages" PR** which is kept up-to-date. This PR

     

       130
       130
       +
       documents all changes that are made and will show in its description what all new changelogs are

     

       131
       131
       +
       going to contain for their new entries.

     

       132
       132
       +
       

     

       133
       133
       +
       Once a "Version Packages" PR is approved by a contributor and merged, the action will automatically

     

       134
       134
       +
       take care of creating the release, publishing all updated packages to the npm registry, and creating

     

       135
       135
       +
       appropriate tags on GitHub too.

     

       136
       136
       +
       

     

       137
       137
       +
       This process is automated, but the changelog should be checked for errors.

     

       138
       138
       +
       

     

       139
       139
       +
       As to **when** to merge the automated PR and publish? Maybe not after every change. Typically there

     

       140
       140
       +
       are two release batches: hotfixes and release batches. We expect that a hotfix for a single package

     

       141
       141
       +
       should go out as quickly as possible if it negatively affects users. For **release batches**

     

       142
       142
       +
       however, it's common to assume that if one change is made to a package that more will follow in the

     

       143
       143
       +
       same week. So waiting for **a day or two** when other changes are expected will make sense to keep the

     

       144
       144
       +
       fatigue as low as possible for downstream maintainers.

     

       145
       145
       +
       

     

       146
       146
       +
       ## How do I upgrade all dependencies?

     

       147
       147
       +
       

     

       148
       148
       +
       It may be a good idea to keep all dependencies on this repository **up-to-date** every now and

     

       149
       149
       +
       then. Typically we do this by running `pnpm update --interactive --latest` and checking one-by-one

     

       150
       150
       +
       which dependencies will need to be bumped. In case of any security issues it may make sense to

     

       151
       151
       +
       just run `pnpm update [package]`.

     

       152
       152
       +
       

     

       153
       153
       +
       While this is rare with `pnpm`, upgrading some transitive dependencies may accidentally duplicate

     

       154
       154
       +
       them if two packages depend on different compatible version ranges. This can be fixed by running:

     

       155
       155
       +
       

     

       156
       156
       +
       ```sh

     

       157
       157
       +
       pnpm dedupe

     

       158
       158
       +
       pnpm install

     

       159
       159
       +
       ```

     

       160
       160
       +
       

     

       161
       161
       +
       It's common to then **create a PR** (with a changeset documenting the packages that need to reflect

     

       162
       162
       +
       new changes if any `dependencies` have changed) with the name of

     

       163
       163
       +
       "(chore) - Upgrade direct and transitive dependencies" or something similar.