1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
---
layout: guide
doc_stub: false
search: true
enterprise: true
section: GraphQL Enterprise - Changesets
title: Releasing Changesets
desc: Associating changes to version numbers
index: 3
---
To be available to clients, Changesets added to the schema with `use GraphQL::Enterprise::Changeset::Release changeset_dir: "..."`:
```ruby
class MyAppSchema < GraphQL::Schema
# Add this before root types so that newly-added types are also added to the schema
use GraphQL::Enterprise::Changeset::Release, changeset_dir: "app/graphql/changesets"
query(...)
mutation(...)
subscription(...)
end
```
This attaches each Changeset defined in `app/graphql/changesets/*.rb` to the schema. (It assumes Rails conventions, where an underscored file like `app/graphql/changesets/add_some_feature.rb` contains a class like `Changesets::AddSomeFeature`.)
{% callout warning %}
Add `GraphQL::Enterprise::Changeset::Release` _before_ hooking up your root `query(...)`, `mutation(...)`, and `subscription(...)` types. Otherwise, the schema may not find links to types in new schema versions.
{% endcallout %}
Alternatively, Changesets can be explicitly attached using `changesets: [...]`, for example:
```ruby
class MyAppSchema < GraphQL::Schema
use GraphQL::Enterprise::Changeset::Release, changesets: [
Changesets::DeprecateRecipeFlag,
Changesets::RemoveRecipeFlag,
]
# ...
end
```
Only changesets in the directory (or in the array) will be shown to clients. The `release ...` configuration in the changeset will be compared to `context[:changeset_version]` to determine if the changeset applies to the current request.
## Inspecting Releases
To preview releases, you can create schema dumps by passing `context: { changeset_version: ... }` to {{ "Schema.to_definition" | api_doc }}.
For example, to see how the schema looks with `API-Version: 2021-06-01`:
```ruby
schema_sdl = MyAppSchema.to_definition(context: { changeset_version: "2021-06-01"})
# The GraphQL schema definition for the schema at version "2021-06-01":
puts schema_sdl
```
To make sure schema versions don't change unexpectedly, use the techniques described in the {% internal_link "Schema structure guide", "/testing/schema_structure" %}.
### Introspection Methods
You can also inspect a schema's changesets programmatically. `GraphQL::Enterprise` adds a `Schema.changesets` method which returns a `Set` of changeset classes:
```ruby
MySchema.changesets
# #<Set: {AddNewFeature, RemoveOldFeature}>
```
Additionally, each changeset has a `.changes` method describing its modifications:
```ruby
AddNewFeature.changes
# [
# #<GraphQL::Enterprise::Changeset::Change: ...>,
# #<GraphQL::Enterprise::Changeset::Change: ...>,
# #<GraphQL::Enterprise::Changeset::Change: ...>,
# ...
# ]
```
Each `Change` object responds to:
- `.member`, the part of the schema that was modified
- `.type`, the kind of modification (`:addition` when something new is added, `:removal` when a member is removed or replaced with a new definition)
|
