From 1803a486d6d2712f4831990dcdb2dd9fafd10ecd Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Tue, 21 Mar 2023 07:23:42 +0000 Subject: [PATCH] chore: Set up GH templates --- .github/FUNDING.yml | 2 + .github/ISSUE_TEMPLATE/RFC.md | 42 +++++++ .github/ISSUE_TEMPLATE/bug_report.yaml | 46 +++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/PULL_REQUEST_TEMPLATE.md | 22 ++++ CONTRIBUTING.md | 163 +++++++++++++++++++++++++ 6 files changed, 283 insertions(+) create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/RFC.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yaml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..66a3f7d --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +github: urql-graphql +open_collective: urql-graphql diff --git a/.github/ISSUE_TEMPLATE/RFC.md b/.github/ISSUE_TEMPLATE/RFC.md new file mode 100644 index 0000000..a90abab --- /dev/null +++ b/.github/ISSUE_TEMPLATE/RFC.md @@ -0,0 +1,42 @@ +--- +name: 'RFC' +about: Propose an enhancement / feature and start a discussion +title: 'RFC: Your Proposal' +labels: "future \U0001F52E" +--- + + + +## Summary + + + +## Proposed Solution + + + +## Requirements + + diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml new file mode 100644 index 0000000..18bd8ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -0,0 +1,46 @@ +name: "\U0001F41E Bug report" +description: Report an issue with graphql.web +labels: [] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: textarea + id: bug-description + attributes: + label: Describe the bug + description: Please describe your bug clearly and concisely. + placeholder: Bug description + validations: + required: true + - type: input + id: reproduction + attributes: + label: Reproduction + description: Please provide a reproduction link, e.g. to a sandbox + placeholder: Reproduction + validations: + required: true + - type: textarea + id: version + attributes: + label: Package version + description: The versions of the relevant urql packages you are using + placeholder: "@0no-co/graphql.web@0.1.0" + validations: + required: true + - type: checkboxes + id: checkboxes + attributes: + label: Validations + description: Before submitting the issue, please make sure you do the following + options: + - 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 + required: true + - label: Follow our [Code of Conduct](https://github.com/0no-co/graphql.web/blob/main/CODE_OF_CONDUCT.md) + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..288cd25 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Ask a question + url: https://github.com/0no-co/graphql.web/discussions + about: Ask questions and discuss with other community members + - name: Join the Discord + url: https://discord.gg/Hw8FR8qKfC + about: Chat with maintainers and other community members diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..0dcde7b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ + + +## Summary + + + +## Set of changes + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6df8538 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,163 @@ +# Development + +Thanks for contributing! We want to ensure that `@0no-co/graphql-web` evolves +and fulfills its idea of making client-side GraphQL smaller and faster! + +## How to contribute? + +We follow fairly standard but lenient rules around pull requests and issues. +Please pick a title that describes your change briefly, optionally in the imperative +mood if possible. + +If you have an idea for a feature or want to fix a bug, consider opening an issue +first. We're also happy to discuss and help you open a PR and get your changes +in! + +- If you have a question, try [creating a GitHub Discussions thread.](https://github.com/0no-co/graphql.web/discussions/new/choose) +- If you think you've found a bug, [open a new issue.](https://github.com/0no-co/graphql.web/issues/new) +- or, if you found a bug you'd like to fix, [open a PR.](https://github.com/0no-co/graphql.web/compare) +- 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). + +### What are the issue conventions? + +There are **no strict conventions**, but we do have two templates in place that will fit most +issues, since questions and other discussion start on GitHub Discussions. The bug template is fairly +standard and the rule of thumb is to try to explain **what you expected** and **what you got +instead.** Following this makes it very clear whether it's a known behavior, an unexpected issue, +or an undocumented quirk. + +### How do I propose changes? + +We follow an **RFC proposal process**. This allows anyone to propose a new feature or a change, and +allows us to communicate our current planned features or changes, so any technical discussion, +progress, or upcoming changes are always **documented transparently.** You can [find the RFC +template](https://github.com/0no-co/graphql.web/issues/new/choose) in our issue creator. + +### What are the PR conventions? + +This also comes with **no strict conventions**. We only ask you to follow the PR template we have +in place more strictly here than the templates for issues, since it asks you to list a summary +(maybe even with a short explanation) and a list of technical changes. + +If you're **resolving** an issue please don't forget to add `Resolve #123` to the description so that +it's automatically linked, so that there's no ambiguity and which issue is being addressed (if any) + +You'll find that a comment by the "Changeset" bot may pop up. If you don't know what a **changeset** +is and why it's asking you to document your changes, read on at ["How do I document a change for the +changelog"](#how-do-i-document-a-change-for-the-changelog) + +We also typically **name** our PRs with a slightly descriptive title, e.g. `feat: Title`. + +## How do I set up the project? + +Luckily it's not hard to get started. You can install dependencie +[using `pnpm`](https://pnpm.io/installation#using-corepack). +Please don't use `npm` or `yarn` to respect the lockfile. + +```sh +pnpm install +``` + +There are multiple commands you can run in the root folder to test your changes: + +```sh +# TypeScript checks: +pnpm run check + +# Linting (prettier & eslint): +pnpm run lint + +# Unit Tests: +pnpm run test + +# Builds: +pnpm run build +``` + +## How do I test my changes? + +It's always good practice to run the tests when making changes. If you're unsure which packages +may be affected by your new tests or changes you may run `pnpm test` in the root of +the repository. + +If your editor is not set up with type checks you may also want to run `pnpm run check` on your +changes. + +Additionally you can head to any example in the `examples/` folder +and run them. There you'll also need to install their dependencies as they're isolated projects, +without a lockfile and without linking to packages in the monorepos. +All examples are started using the `package.json`'s `start` script. + +## How do I lint my code? + +We ensure consistency in this codebase using `eslint` and `prettier`. +They are run on a `precommit` hook, so if something's off they'll try +to automatically fix up your code, or display an error. + +If you have them set up in your editor, even better! + +## How do I document a change for the changelog? + +This project uses [changesets](https://github.com/atlassian/changesets). This means that for +every PR there must be documentation for what has been changed and which package is affected. + +You can document a change by running `changeset`, which will ask you which packages +have changed and whether the change is major/minor/patch. It will then ask you to write +a change entry as markdown. + +```sh +# In the root of the urql repository call: +pnpm changeset +``` + +This will create a new "changeset file" in the `.changeset` folder, which you should commit and +push, so that it's added to your PR. +This will eventually end up in the package's `CHANGELOG.md` file when we do a release. + +You won't need to add a changeset if you're simply making "non-visible" changes to the docs or other +files that aren't published to the npm registry. + +[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) + +## How do I release new versions of our packages? + +Hold up, that's **automated**! Since we use `changeset` to document our changes, which determines what +goes into the changelog and what kind of version bump a change should make, you can also use the +tool to check what's currently posed to change after a release batch using: `pnpm changeset status`. + +We have a [GitHub Actions workflow](./.github/workflow/release.yml) which is triggered whenever new +changes are merged. It will always open a **"Version Packages" PR** which is kept up-to-date. This PR +documents all changes that are made and will show in its description what all new changelogs are +going to contain for their new entries. + +Once a "Version Packages" PR is approved by a contributor and merged, the action will automatically +take care of creating the release, publishing all updated packages to the npm registry, and creating +appropriate tags on GitHub too. + +This process is automated, but the changelog should be checked for errors. + +As to **when** to merge the automated PR and publish? Maybe not after every change. Typically there +are two release batches: hotfixes and release batches. We expect that a hotfix for a single package +should go out as quickly as possible if it negatively affects users. For **release batches** +however, it's common to assume that if one change is made to a package that more will follow in the +same week. So waiting for **a day or two** when other changes are expected will make sense to keep the +fatigue as low as possible for downstream maintainers. + +## How do I upgrade all dependencies? + +It may be a good idea to keep all dependencies on this repository **up-to-date** every now and +then. Typically we do this by running `pnpm update --interactive --latest` and checking one-by-one +which dependencies will need to be bumped. In case of any security issues it may make sense to +just run `pnpm update [package]`. + +While this is rare with `pnpm`, upgrading some transitive dependencies may accidentally duplicate +them if two packages depend on different compatible version ranges. This can be fixed by running: + +```sh +pnpm dedupe +pnpm install +``` + +It's common to then **create a PR** (with a changeset documenting the packages that need to reflect +new changes if any `dependencies` have changed) with the name of +"(chore) - Upgrade direct and transitive dependencies" or something similar. -- knotmirror 0.0.1