Removing "value types" and introducing the @shareable directive #1560

rkoron007 · 2022-03-02T23:09:29Z

This PR documents how to use the @shareable directive and removes the previous instructions for creating "value types."

codesandbox-ci · 2022-03-02T23:10:30Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

docs/source/federated-types/composition.mdx

docs/source/federation-2/moving-to-federation-2.mdx

docs/source/federated-types/sharing-types.mdx

StephenBarlow · 2022-03-04T00:04:12Z

docs/source/federated-types/sharing-types.mdx

+
+> ⚠️ The field sharing model has changed significantly in Federation 2. For a summary of these changes, [see what's new](/federation-2/new-in-federation-2/#value-types). 
+>
+>For more information about using value types in Federation 1, you can view the [previous version of this article here](https://www.apollographql.com/docs/federation/value-types/).


StephenBarlow · 2022-03-04T00:07:40Z

docs/source/federated-types/sharing-types.mdx

+
+Shared fields can differ between subgraphs in specific ways:
+* The return type of a shared field can vary in nullability (`String` / `String!`).
+  * A shared field's return type can't vary in its core type (`Int` vs. `String`) or in whether it returns a list (`Int` vs. `[Int]`).


Italicize "can't"

StephenBarlow · 2022-03-04T00:10:19Z

docs/source/federated-types/sharing-types.mdx

+
+This can be useful when different subgraphs are responsible for different subsets of a particular set of related types or values.
+
+## Varying shared fields


Suggest "Varying shared object fields"

StephenBarlow · 2022-03-04T00:16:51Z

docs/source/federated-types/sharing-types.mdx

+
+This article describes how to share a [GraphQL object type's](https://www.apollographql.com/docs/apollo-server/schema/schema/#object-types) fields in a federated graph, enabling multiple subgraphs to define and resolve those shared fields. 
+
+## Using `@shareable`


I think we can deduplicate some content in this article and end up with the following header structure:

Sharing object types

Varying shared fields

Differing return types

Omitting fields

Enums, unions, and interfaces

All the stuff currently under "Using @shareable" can go under "Sharing object types". The subgraph examples in those two existing sections have a lot of overlap, so I think they'll merge nicely. Let me know if that doesn't sound correct!

StephenBarlow · 2022-03-04T00:19:15Z

docs/source/federated-types/sharing-types.mdx

+  YELLOW
+}
+
+# The object types that implement this interface are


I think the interface story is a little more complicated than we currently describe here. I need to do some research 🤔

Yeah...the main point I wanted to get across was that you can add/redefine fields in interfaces across multiple subgraphs without explicit sharing (and that's okay because interfaces don't technically resolve their own fields). If the faux "supergraph schema" is confusing I can ask around and see if there is a better way to represent this?

Totally, it's a good example to include! I'm just not sure whether there are extra concerns to highlight for interfaces, I need to reread some of the big design docs

* First pass * Adding shareable in different articles * Almost done with main sharing article * Updating implict vs explicit sharing * Final pass to ensuring sharing types info is accurate everywhere * Remove package lock changes * Fix links for deploy preview * Start working through feedback * Add first round of feedback * Fix broken links * Restructure Sharing article

* WIP on edits for preview * More WIP mostly on entities * More WIP entity work * Fix broken links * Incorporate some feedback, remove extend keywords, add shareable directives * Edits to Moving to Fed 2 article * Fix broken link * Clarity edits * Majorly reorganize main entities article * Fix broken links * Add entity info to what's new * Removing "value types" and introducing the @Shareable directive (#1560) * First pass * Adding shareable in different articles * Almost done with main sharing article * Updating implict vs explicit sharing * Final pass to ensuring sharing types info is accurate everywhere * Remove package lock changes * Fix links for deploy preview * Start working through feedback * Add first round of feedback * Fix broken links * Restructure Sharing article * Condense sharing article and reintroduce value type * Clarify support matrix and add more fed2 snippets * Incorporate feedback, reintroduce more value type language * Tweak entity migration steps to not cause failed composition * Add another step for modifying fed2 schemas * Remove temporary section * Fix phantom link * Incorporate last bit of suggestions * Fix broken links * Prepare gatsby config * Update preview version numbers * Bump gateway version number for fed2 preview Co-authored-by: Rose M Koron <32436232+rkoron007@users.noreply.github.com>

rkoron007 requested a review from StephenBarlow March 2, 2022 23:09

rkoron007 self-assigned this Mar 2, 2022