Merge remote-tracking branch 'origin/main' into HEAD

.github/workflows/go.yml

@@ -12,11 +12,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '1.18', '1.19', '1.20' ]
+        go: [ '1.20', '1.21', '1.22' ]
 
     steps:
     - name: Set up Go
-      uses: actions/setup-go@v1
+      uses: actions/setup-go@v4
       with:
         go-version: ${{ matrix.go }}
       id: go
@@ -36,10 +36,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.22'
+      id: go
+
     - name: Git checkout
       uses: actions/checkout@v2
 
     - name: Run lint
-      uses: golangci/golangci-lint-action@v2
+      uses: golangci/golangci-lint-action@v3
       with:
-        version: v1.52.2   # should match internal/lint/go.mod
+        version: v1.56.1   # should match internal/lint/go.mod

.golangci.yml

@@ -42,14 +42,19 @@ linters-settings:
 
   # We have a ton of test-only packages; but make sure we keep prod deps small.
   depguard:
-    list-type: whitelist
-    packages:
-      - github.com/Khan/genqlient
-      - github.com/vektah/gqlparser/v2
-      - golang.org/x/tools
-      - gopkg.in/yaml.v2
-      - github.com/alexflint/go-arg
-      - github.com/google/uuid
+    rules:
+      main:
+        list-mode: strict
+        files: $all
+        allow:
+          - $gostd
+          - github.com/Khan/genqlient
+          - github.com/vektah/gqlparser/v2
+          - golang.org/x/tools
+          - gopkg.in/yaml.v2
+          - github.com/alexflint/go-arg
+          - github.com/bmatcuk/doublestar/v4
+          - github.com/google/uuid
 
   forbidigo:
     forbid:

README.md

@@ -19,7 +19,7 @@ genqlient provides:
 
 ## How do I use genqlient?
 
-You can download and run genqlient the usual way: `go run github.com/Khan/genqlient`.  To set your project up to use genqlient, see the [getting started guide](docs/INTRODUCTION.md), or the [example](example).  For more complete documentation, see the [docs](docs).
+You can download and run genqlient the usual way: `go run github.com/Khan/genqlient`.  To set your project up to use genqlient, see the [getting started guide](docs/introduction.md), or the [example](example).  For more complete documentation, see the [docs](docs).
 
 ## How can I help?
 
@@ -47,6 +47,6 @@ This code works, but it has a few problems:
 - The GraphQL variables aren't type-safe at all; you could have passed `{"id": true}` and again you won't know until runtime!
 - You have to write everything twice, or hide the query in complicated struct tags, or give up what type safety you do have and resort to `interface{}`.
 
-These problems aren't a big deal in a small application, but for serious production-grade tools they're not ideal.  And they should be entirely avoidable: GraphQL and Go are both typed languages; and GraphQL servers expose their schema in a standard, machine-readable format.  We should be able to simply write a query and have that automatically validated against the schema and turned into a Go struct which we can use in our code.  In fact, there's already good prior art to do this sort of thing: [99designs/gqlgen](https://github.com/99designs/gqlgen) is a popular server library that generates types, and Apollo has a [codegen tool](https://www.apollographql.com/docs/devtools/cli/#supported-commands) to generate similar client-types for several other languages.  (See [docs/DESIGN.md](docs/DESIGN.md) for more prior art.)
+These problems aren't a big deal in a small application, but for serious production-grade tools they're not ideal.  And they should be entirely avoidable: GraphQL and Go are both typed languages; and GraphQL servers expose their schema in a standard, machine-readable format.  We should be able to simply write a query and have that automatically validated against the schema and turned into a Go struct which we can use in our code.  In fact, there's already good prior art to do this sort of thing: [99designs/gqlgen](https://github.com/99designs/gqlgen) is a popular server library that generates types, and Apollo has a [codegen tool](https://www.apollographql.com/docs/devtools/cli/#supported-commands) to generate similar client-types for several other languages.  (See the [design note](docs/design.md) for more prior art.)
 
 genqlient fills that gap: you just specify the query, and it generates type-safe helpers, validated against the schema, that make the query.

docs/CHANGELOG.md

@@ -22,25 +22,44 @@ When releasing a new version:
 
 ### Breaking changes:
 
+- omitempty validation:
+  - forbid `omitempty: false` (including implicit behaviour) when using pointer on non-null input field
+
+### New features:
+
+- genqlient now supports double-star globs for schema and query files; see [`genqlient.yaml` docs](genqlient.yaml) for more.
+
+### Bug fixes:
+
+- omitempty validation:
+  - allow `omitempty` on non-nullable input field, if the field has a default
+  - allow `omitempty: false` on an input field, even when it is non-nullable
+- don't do `omitempty` and `pointer` input types validation when `use_struct_reference` is used, as the generated type is often not compatible with validation logic.
+
+## v0.7.0
+
+In addition to several new features and bugfixes, along with this release comes reorganized [documentation](.) for genqlient. Note that genqlient now requires Go 1.20 or higher, and is tested through Go 1.22.
+
 ### New features:
 
 - genqlient now supports subscriptions; the websocket protocol is by default `graphql-transport-ws` but can be set to another value.  
   See the [documentation](FAQ.md) for how to `subscribe to an API 'subscription' endpoint`.
 - The new `optional: generic` allows using a generic type to represent optionality. See the [documentation](genqlient.yaml) for details.
 - For schemas with enum values that differ only in casing, it's now possible to disable smart-casing in genqlient.yaml; see the [documentation](genqlient.yaml) for `casing` for details.
+- genqlient now supports .graphqls and .gql file extensions for schemas and queries.
+- More accurately guess the package name for generated code (and warn if the config option -- now almost never needed -- looks wrong).
 
 ### Bug fixes:
-- The presence of negative pointer directives, i.e., `# @genqlient(pointer: false)` are now respected even in the when `optional: pointer` is set in the configuration file.
+- Negative pointer directives, i.e., `# @genqlient(pointer: false)` are now respected even in the when `optional: pointer` is set in the configuration file.
 - Made name collisions between query/mutation arguments and local function variables less likely.
+- Fix generation issue related to golang type implementation of complex graphql union fragments.
+- Bind correctly to types in the same package as the generated code.
+- Fix non-deterministic generated code when querying graphql interfaces via named fragments.
 
 ## v0.6.0
 
 Version 0.6.0 includes some small features and bugfixes. Note that genqlient now requires Go 1.18 or higher, and is tested through Go 1.20.
 
-### Breaking changes:
-
-- genqlient now requires Go 1.18 or higher.
-
 ### New features:
 
 - You can now bind all types from a package in `genqlient.yaml` using the new `package_bindings` option.
@@ -59,7 +78,6 @@ Version 0.5.0 adds several new configuration options and convenience features. N
 
 ### Breaking changes:
 
-- genqlient now requires Go 1.16 or higher.
 - The [`graphql.Client`](https://pkg.go.dev/github.com/Khan/genqlient/graphql#Client) interface now accepts two structs for the request and response, to allow future expansion, rather than several individual arguments.  Clients implementing the interface themselves will need to change the signature; clients who simply call `graphql.NewClient` are unaffected.
 
 ### New features:
@@ -107,9 +125,9 @@ Version 0.3.0 adds several new configuration options, allowing simplification of
 
 ### New features:
 
-- genqlient's types are now safe to JSON-marshal, which can be useful for putting them in a cache, for example.  See the [docs](FAQ.md#-let-me-json-marshal-my-response-objects) for details.
-- The new `flatten` option in the `# @genqlient` directive allows for a simpler form of type-sharing using fragment spreads.  See the [docs](FAQ.md#-shared-types-between-different-parts-of-the-query) for details.
-- The new `for` option in the `# @genqlient` directive allows applying options to a particular field anywhere it appears in the query.  This is especially useful for fields of input types, for which there is otherwise no way to specify options; see the [documentation on handling nullable fields](FAQ.md#-nullable-fields) for an example, and the [`# @genqlient` directive reference](genqlient_directive.graphql) for the full details.
+- genqlient's types are now safe to JSON-marshal, which can be useful for putting them in a cache, for example.  See the [docs](client_config.md#marshaling) for details.
+- The new `flatten` option in the `# @genqlient` directive allows for a simpler form of type-sharing using fragment spreads.  See the [docs](operations.md#sharing-types) for details.
+- The new `for` option in the `# @genqlient` directive allows applying options to a particular field anywhere it appears in the query.  This is especially useful for fields of input types, for which there is otherwise no way to specify options; see the [documentation on handling nullable fields](operations.md#nullable-fields) for an example, and the [`# @genqlient` directive reference](genqlient_directive.graphql) for the full details.
 
 ### Bug fixes:
 

docs/CONTRIBUTING.md

@@ -22,9 +22,9 @@ Pull requests should have:
 - documentation, for new features
 - changelog entries
 
-Pull requests will be squash-merged, so subsequent commit messages may be brief (e.g. "review comments").
+The PR description template will remind you of these. Pull requests will be squash-merged, so subsequent commit messages may be brief (e.g. "review comments").
 
-Large changes should typically be discussed on the issue tracker first, and should ideally be broken up into separate PRs, or failing that, several commits, for ease of reviewing.
+Large changes should typically be discussed on the issue tracker first, and should ideally be broken up into separate PRs, or failing that, several commits, for ease of reviewing. This is especially true of breaking changes; see the [versioning policy](versioning.md) for what we consider breaking.
 
 ## Style
 
@@ -44,11 +44,11 @@ If you update any code-generation logic or templates, even if no new tests are n
 
 ## Finding your way around
 
-If you're new to genqlient, start out by reading the source of `generate.Generate`, whose comments describe most of the high-level operation of genqlient.  In general, the code is documented inline, often with an introductory comment at the top of the file.  See [DESIGN.md](DESIGN.md) for documentation of major design decisions, which is a good way to get a sense of why genqlient is structured the way it is.
+If you're new to genqlient, start out by reading the source of `generate.Generate`, whose comments describe most of the high-level operation of genqlient.  In general, the code is documented inline, often with an introductory comment at the top of the file.  See the [design note](design.md) for documentation of major design decisions, which is a good way to get a sense of why genqlient is structured the way it is.
 
 ## Making a release
 
-We try to cut releases periodically. To make a release:
+See the [versioning strategy](versioning.md) for when to make a release. To make a release:
 
 - Scan PRs since the last release to check we didn't miss anything in the changelog.
 - Check if there are any regressions or major problems with new features we want to fix before cutting the release.