Feature: Schema Ownership

[kamilkisiela]

Option 1: We can use the codebase itself to parse CODEOWNERS files.

Option 2: Allow parsing the schemas with something like:

# CODEOWNERS: dotansimha
type User {
  id: ID!
}

Option 3: we can use the Hive CLI for scanning CODEOWNERS in the fs and then annotate the schema with the GraphQL comment from option 2.

This way we can introduce:

• Visibility of ownership of each type/field/service
• Build a tool for schema approvals - we can communicate it to the Reviewers of a PR back to GitHub, or even add a schema publication check and look for the owners approvals.
• Build a tool for changes visibility - when a schema adds a new reference to a GraphQL type, we can notify the owner of that type/service that the type was used.

I guess we need GH integration first, but it's a good chance to add that.

[n1ru4l]

Related: #2747

[comatory]

I wanted to add some suggestions which would work good in our organization:

1. Allow multiple codeowners, e.g. #CODEOWNERS: person1, person2
2. Not sure if it's apparent but in our case the codeowner wouldn't usually be a person but a team so more like #CODEOWNERS: @team-1
3. Our setup is that usually the whole subgraph is owned by some team but in some cases, fields or types can be owned by someone else. Not sure what would be good solution here.
4. Adding codeowner to specific field would also help, I wonder if this would be possible:

# CODEOWNERS: @team-1
type User {
  id: ID!
  # CODEOWNERS: @team-2, @team-3
  posts: PostConnection!
}

I love the idea with schema approvals built into the tool. Our setup at the moment is that we have internal schema governor Github team which owns generated .graphql files in every repo, so we do that in Github. But having optional ability to approve the schema by separate group of people would work well with federated graph.

[n1ru4l]

I think we should probably solve this with schema directives, something like the following:

type User @codeOwners(teams: ["team-1"]) {
  id: ID!
  posts: PostConnection! @codeOwners(teams: ["team-2", "team-3"])
}

[n1ru4l]

Apollo Federation also supports schema ownership through directives: https://www.apollographql.com/docs/technotes/TN0036-owner-pattern/

directive @owner(team: String!) on OBJECT

[comatory]

Apollo Federation also supports schema ownership through directives: https://www.apollographql.com/docs/technotes/TN0036-owner-pattern/

directive @owner(team: String!) on OBJECT

Thanks, I see that it's only for Federation v2 though but it's definitely good to know. Do you happen to know if GraphQL Fusion spec will suport such directive?

Anyway I think we're talking about two related things here but maybe it's important to make the distinction

1. Having visibility into ownership via UI in Hive
2. Adding the ownership metadata

I think for #2, there's few more things I'd like to consider:

2a. leveraging CODEOWNERS file

Our setup often has multiple subschemas defined in single repository, they all get published separately to Hive. The "codeowners" file then contains entry like this:

src/module-1/schema.graphql @team-1

This is great because we can get triggered on code reviews when that file changes. But perhaps Hive could have a way of marking @team-1 to be owners of the whole sub-schema. I'm not sure how this would work in practice though. Adding field/type/mutation etc. annotation everywhere might make inspecting the schema messy (but I'd probably take that).

On the other hand there could be a comment on top of the file:

# CODEOWNERS: @team-1

Hive could then parse this so everything would be considered being owned by @team-1 unless overridden with a directive (ofc it should exclude federated fields). This comment could be generated by Hive CLI by looking at repository's CODEOWNERS file or maybe by passing some metadata when publishing.

2b. overriding ownership with directives

This could work regardless of top-level comment mentioned in 2a. Basically it'd be something added manually for specific parts of sub-schema. But if the top-level comment was present, the given field containing ownership directive would override that. When inspecting the schema with eyeballs, it would make it still human readable.

IDK, does it make sense to you? I'm just trying to thing of easy way to have granular ownership while still leveraging CODEOWNERS file.