Skip to content

2022-11.md

Latest commit

 

History

History
455 lines (428 loc) · 26.6 KB

2022-11.md

File metadata and controls

455 lines (428 loc) · 26.6 KB

GraphQL WG Notes - November 2022

Watch the replays: GraphQL Working Group Meetings on YouTube

Primary meeting

Agenda

Determine volunteers for note taking (1m, Lee)

  • Benjie
  • Stephen

Review agenda (2m, Lee)

  • Hugh: how have people found the new cadence?
    • Michael: seems good so far. Smaller slot is nice. Australia slot - I hope more people join in future.
    • Lee: we had a healthy audience for the first APAC meeting; mostly Australia, but hopefully we'll make more noise and make that pick up.
    • Michael: we need to spread the word a bit.
    • Uri: are we using the official GraphQL twitter account?
    • Lee: we can.
    • Michael: perhaps Uri can reach out to more maintainers.
    • Lee: I'll tweet something about that later today.
    • Lee: Adding a recap to the meetings would be nice
    • Lee: did the secondary EU meeting go well?
    • Benjie: yeah, low attendance but interesting and went well. I didn't have access to Zoom until recently so haven't been able to upload the videos yet.
    • Michael: I attended, good stuff for the first meeting.
    • Lee: custom scalars was the main discussion; picking up the repository and website. There's a good template in place now.
    • Michael: the scalar stuff is on the next agenda to be picked up too.
    • Lee: There was 11 people in the secondary meeting - very well attended. There was discussion around structs, around SDUI, …, and we ran out of time for other topics.
  • Lee: the next phase of the GraphQL community grant is launching. The form has been always open, but we're going to officially decide on granting a few of these at the close of this month so that we can hopefully get it started next year. Some folks here might want to apply, but we should also promote it on other channels. If there are projects that we want to sponsor, Google Summer-of-Code style, we could put a section on the Foundation website saying here are things that we hope people will do. Documentation would be a great use of community grants.
    • Benjie: maybe we can reach out to all the maintainers across the GraphQL repositories?
    • Lee: there's a @graphql/maintainers that we could ping in GitHub Discussions.
    • Michael: we should retweet on the GraphQL Twitter because sometimes people miss it in GitHub.
    • Lee: indeed, collecting information from the main contributors would be a good project because we don't have a good way to reach out to them.
    • Lee: I'm going to open a GitHub discussion
    • Hugh: we've used a Devrel tool at Apollo called Orbit; it's great at connecting to different sources like GitHub and tagging people so you can reach out to them in future, e.g. "GraphQL OSS contributors". https://orbit.love
    • Lee: #1165

Review previous meeting's action items (5m, Lee)

Status of express-graphql project (5m, Benjie)

  • Last published 2 years ago
  • GraphQL Foundation is receiving emails about it
  • People are concerned that it doesn’t support GraphQL-16. Hasn’t been a release in two years. Are we still maintaining it? Still a reference impl? Or should we archive it.
  • Michael: I wouldn’t archive it. Especially with GraphQL-over-HTTP spec on the horizon, this could be implemented there
  • Matt: +1
  • Hugh: Ivan has some time to work on it
  • Ivan: We discussed for GraphQL.js how to not have it depend on a single person.
    • Solution: a review team. 5 people from different organizations. They have admin access.
    • Important to discuss differences between code ownership and those participating in WGs. WG is welcome, but not everyone will have aptitude or interest. Part of maintainers burdon is contributors submitting nonstandard code.
    • Will do a release today
    • Identify serial contributors ask to join as reviewer
  • Uri: Happy to see several merged PRs today, but in last few years not much
    • This uses express. Not necessarily the default.
    • Should ref impl determine which http framework you use?
    • GraphQL-over-HTTP working group. Testing library to validate framework to see if it follows the spec
    • There are other server impls that have active communities. People might try to use the reference impl, and I wouldn’t recommend that because it isn’t as actively maintained.
    • Are we doing more harm by having it out there?
    • The last person to maintain the library was Daniel. He went on to a different project with a different vision
    • I believe the having all of the pieces with suite of tests we get what we would want from a reference implementation
  • Michael: It's good having a testing library, but the reference example is useful - e.g. Apollo Server, Helix, etc all add more than the spec. It's a good thing to look at how someone has implemented the spec text, so I think it's valuable.
  • Derek: I think a reference implementation is good. Maybe the foundation can put some funds in (pay someone to keep it up to date)
  • Lee: we have the community grant!
  • Denis: A reference implementation should not just be something that implements the specification - it should be something that you can read code-wise and then implement in any other language. GraphQL-HTTP is written with this idea in mind, it's simple, it's server-agnostic, and shows how you could implement this yourself in JS or in any other programming language. I've also gone through the GraphQL over HTTP spec and wrote a regression suite for it that you can run against any GraphQL over HTTP API. The name express-graphql also brings this expectation that it's to be used with Express, which is an older framework now. I'm already keeping this up to date with the GraphQL-over-HTTP spec, I enjoy doing this.
  • Lee: we have the right input. Clear: loads of people are using express-graphql (can we make sure these dependencies don't break); either we have to support it in the short term (thanks Ivan for merging PRs). We may need an exit plan - what does it look like to migrate from this to something else. I agree with your statement of goals, Denis. Ultimately someone needs to own this, own the space, and my opinion is that that person should be deep in the weeds of GraphQL-over-HTTP. Denis, if you want to be that, it would make sense for us to put our trust in you that this goes smoothly.
  • Denis: I don't think there'll be much friction moving from express-graphql to graphql-http, but we can create a migration plan.
  • Hugh: does this mean graphql-http needs to become a Foundation owned project.
  • Lee: there's ambiguity over what the reference implementation is. The reference implementation should live within the GraphQL org, which shouldn't affect your ability to manage it.
  • Denis: I want to have ultimate control of it, be able to change the code how I want, and govern the code style of the repo. If that's okay with everyone then I'm happy it living under the GraphQL foundation.
  • Michael: these things are typically owned by one person, so I think that's fine.
  • Lee: there are technical changes (e.g. it'll be managed by the technical group), but how you want to operate it should work fine.
  • Uri: does upgrading express-graphql send the wrong message? Maybe we should send a very clear message on express-graphql itself that it's not maintained and people should not use it. Do we need to move it under the Foundation? At the Guild we have this philosophy that Foundation projects move slow (for all sorts of reasons, good reasons); this project is moving quickly and no-one seems to have negative feedback on. We can always fork it (because it's MIT licensed) and move it under the foundation if Denis does anything that we disagree with, but assuming that doesn't happen moving it to Foundation removes some of Denis' credit. And if Denis goes rogue we can always move a fork to the Foundation then. Mostly I'm worried about the projects being maintained for the long term.
  • Lee: our goal should be to make it as valuable a process as possible - if value is lost when it goes into foundation core, then that's not a good process. First: lets give credit! Put a message at the top of the README or similar. The main advantage is that we would be giving a safety net to the community, that should be pure value.
  • Lee: I think the main reason that projects move slow is that they don't have impassioned primary maintainers.
  • Michael: personally I think it gives you more credibility because it's under the Foundation. I definitely don't think you're taking credit away.
  • Lee: let's open a discussions thread if there's any more to discuss here. If graphql-http is the source of truth then we have to make that very clear, and give everyone a good sense of why this is a good thing.

@deprecated on OBJECT (15m, Stephen)

  • Use case: objects that are members of interfaces and unions
  • Spec PR
  • [18:26]
  • Stephen: Use case: [slideshow]. Animal = Dog | Baiji (via interface); but Baiji hasn't been seen for 20 years. Clients' shouldn't be spreading on the Baiji type when looking at the Animal interface. We could mark the Baiji type as deprecated (OBJECT location for @deprecated directive) - indicates to clients not to spread on this. Can be used in tooling, etc. The Baiji type is only referenced as part of an interface, it's never referenced in the schema directly. In the spec I've put a SHOULD NOT to say that you shouldn't have a deprecated object type be referenced by un-deprecated fields.
  • Lee: interesting. The reason for deprecation was that removing something would be a client-side breaking change. Is this a similar case? Removing the object from the union/interface would be a breaking change.
  • Stephen: yes it does, because of validation - if they spread on a type that isn't part of the interface then servers will reject that query.
  • Matt: that exact case has happened, people removing types from an interface and this becoming a breaking change.
  • Lee: Makes sense; the fragment spread itself is the thing that fails validation if you remove a type from an interface.
  • Matt: making it a MUST that a non-deprecated field cannot reference a deprecated type would make that stronger; and make it a validation rule.
  • Lee: deprecation is quite narrow right now; but if you remove everything from the schema that's deprecated then the resulting schema should still be valid. So yes, this is something that should be a MUST for us to stick to this rule.
  • Matt: do we have the rule that if a field is deprecated on a type then it must also be deprecated on any interface?
  • Lee: good question
  • Ivan: no, we don't have this rule.
  • Stephen: sounds like another PR; it probably should - right?
  • Lee: yeah, it's surprising that hasn't come up in the Facebook API.
  • Matt: interface fields tend to be Hack/PHP; everyone gets the same implementation (same code executed) - deprecating it deprecates it everywhere.
  • ACTION - validate this.
  • Stephen: at runtime, should a server be able to return a deprecated object as part of a union/interface.
  • Lee: that's interesting because so far deprecation is about what the client can ask for. We've not needed a mechanism like that.
  • Matt: I don't think it's possible to say that the server cannot return with that deprecated type; you can have a non-nullable deprecated field that returns a deprecated type - so you must return something.
  • Benjie: but that only applies to concrete references rather than interfaces/unions, right?
  • Stephen: is that it's deprecated a promise to the client that it won't appear in a union/interface any more.
  • Matt: we don't make promises about unions/interfaces because clients have to be compatible with future schemas, so this is just like any future type. Your client should be robust to receiving this no-longer expected type.
  • Lee: if the client only looks at the subset of the schema that's not deprecated, then it receiving the deprecated type could be an old type or a new type and they're effectively the same: an unknown (unsupported) type.
  • Stephen: what's the RFC phase of this?
  • Lee: Phase 1; some big open questions, but it's a real problem that people have experienced.
  • Stephen: next steps; change wording to MUST.
  • Lee: for Phase 2 you need consensus that the direction is correct - especially around deprecating the type versus deprecating its membership to an interface/union. And you need a spec PR that shows how it would work.

@defer/@stream discussion (20m, Rob)

  • Spec PR
  • Drop defer/stream support from subscriptions in initial spec proposal?
  • Rob: In the Primary October meeting we spoke about Defer/Stream and subscriptions. It's not clear exactly how to handle this, so we discussed whether we should omit subscriptions support for now to get stream/defer out. We considered adding a validation rule that forbids subscriptions using @defer/@stream, but this means that you can't use fragments in subscriptions that you might use elsewhere that use defer/stream. We also considered doing an execution-phase error. We also considered requiring that the if: argument is used to disable them on subscriptions.
  • Should we be multiplexing these payloads? My implementation waits to drain all responses from the current event before processing the next subscription event.
  • Lee: how much potential churn is there in continuing down the path of multiplexing?
  • Rob: it's not been explored very much, and I definitely think there could be some workshopping/bikeshedding on it.
  • Lee: I feel pretty strongly that we should not make stream/defer all-or-nothing. It may be the case that your implementation has constraints on how payloads are treated for mutations versus queries. Enforcing an implementor to support stream/defer for queries, mutations AND subscriptions, OR none, then that's a rough position to put them in. This seems like an important thing to get right.
  • Matt: I'm a huge fan of using validation rules to get incremental wins when the behavior of what you want to build is not figured out. For example in the spec we could have a directive that you add to query/mutation/subscription like @deferStreamEnabled; then on the server you state you only support defer/stream on queries and if you find defer/stream on other operations then they're not valid.
  • Michael: agree, also validation rules give syntax errors before you even send it to the server. Not a fan of the field error options.
  • Lee: tricky part with validation rule is that there's this additional unknown piece of information that we'd need to add to introspection - does the server support streaming for query/subscription/etc - so that the client knows whether the operation is valid or not.
  • Matt: that seems reasonable to do. E.g. adding a directive to the root Query Mutation Subscription types. We have a whole bunch of servers right now that don't support it,
  • Rob: the case of sharing fragments is my main concern, especially with Relay. It would prevent you using defer in your query if you can't also use it with your mutation/subscription.
  • Michael: in Relay the fragment is bound to a component, right? You tend to have a much smaller footprint for a subscription.
  • Matt: at Meta we'd get into the problems that Rob's explaining. For Relay, Relay has a compiler, we can just strip them out.
  • Hugh: Apollo Client doesn't have a compiler, but we can give a dev-time warning. Users would have to know to do it.
  • Matt: it's impetus for someone running into this problem to solve.
  • Hugh: do we agree that we can move defer/stream ahead without subscriptions?
  • Michael: there's so much good stuff that people could use.
  • Hugh: we've got really promising usage data. There's not been any issues with subscriptions because people aren't thinking about it.
  • Lee: framing it as a user saying "we can't support it in subscriptions, what should we do" is a different way of framing the problem that may help solve it.
  • Lee: I'm favoring option 2 - it doesn't rule out the ability for a tool to add extra validation rules. Untangling how to get around the validation rule would be non-obvious, and figuring out when to apply or not would be non-obvious too.
  • Michael: server can ignore defer, that's okay, so why not just do that?
  • Rob: we talked about that in the primary meeting - is it a breaking change if you had a subscription that never deferred/streamed and now suddenly it does?
  • Matt: yes
  • Michael: it could be.
  • Lee: the forward compatibility problem there is less good.
  • Michael: It's easy to create 3000 patches with a couple streams and a defer. People could use this in a nefarious way against your server, so it's critical that the server can ignore these because they could harm the server. The client should not be fixated on patches, it should deal with different patch styles, different kinds of patches.
  • Lee: we're at time. Rob, you seem to have directionally correct feedback: yes this is a problem that needs solving. Maybe you can explore a little bit about how to apply the disabling?
  • Rob: seems we're not clear on option 1 or 2?
  • Lee: I prefer option 2 but it sounds like there's mixed opinions.
  • Hugh: sounds like we're okay with separating subscriptions out of this.
  • [19:03] Meeting ends

Secondary meeting - APAC

Agenda

  1. Agree to Membership Agreement, Participation & Contribution Guidelines and Code of Conduct (1m, Lee)
  2. Introduction of attendees (5m, Lee)
  3. Determine volunteers for note taking (1m, Lee)
  4. Review agenda (2m, Lee)
  5. Review previous meeting's action items (5m, Lee)
  6. GraphQL Scalars licensing and domain setup (15m, Donna)
  7. References (20m, Yaacov)

Determine volunteers for note taking (1m, Lee)

  • Benjie

Review agenda (2m, Lee)

  • Videos: they've not been uploaded yet? Automation issue?
  • Benjie: there's no automation; I didn't have access to Zoom for a while, so am behind.
  • Donna: {Possible automation suggested for Zoom -> YouTube uploads}
  • Lee: Aim to have more cross-meeting check-ins (recaps, etc)
  • Community grant:
    • If interested, you should apply
    • We should collect proposed focus areas for the grants
      • e.g. website needs work
      • docs could be improved
    • Think about community grants as summer of code - pitch projects and have people apply to do them?
  • Recap: express-graphql had no primary maintainer, isn't up to date with graphql-js, didn't seem like it was best placed for the GraphQL-over-HTTP spec, graphql-http module now implements that spec, and has been moved under the foundation with a stellar maintainer.
  • Recap: defer/stream vs subscriptions: entire domain of stuff that we haven't handled: multiplex or not, what happens if errors happen in the middle, etc? Rob's pitched not having defer/stream on subscriptions, but we still have to figure out HOW to do that.
  • (Yaacov not present, so agenda item bumped.)

GraphQL Scalars licensing and domain setup (15m, Donna)

  • Donna: Aligning license with rest of GraphQL projects
  • Andi: Copied setup process of GraphQL spec to minimize overhead, ease maintenance. Produce HTML, deploy to GitHub pages.
  • Andi: we need a domain entry for scalars.graphql.org
  • Andi: is the domain legally owned by the Foundation?
  • Lee: yes, Linux Foundation has the tools for managing domains. I'll arrange with Elisa.
  • Benjie (chat): https://graphql.github.io/graphql-over-http/ Can we get similar domain for this repo?
  • Lee (chat): yes!
  • Andi: we should use the same license as for the spec, since it's text rather than code?
  • Lee: seems to make sense. Are the specs licensed and owned by GraphQL Foundation? That seems easiest way, especially to allow multiple contributors.
  • Andi: yes, just like spec contributions. Manual review, to ensure it doesn't violate CoC/legals/etc.
  • Andi: if I publish a spec, I want to have it shared, available, etc.
  • Lee: maybe we should have one license doc, rather than copy/pasting legal text into the templates. License file at the top of the repo, and link at the top of the template that says "licensed via {this file}". Then copy/paste the legal text out of GraphQL spec; I'll ensure it's done correctly.
  • Lee: the copyright notice might be not quite the right thing.
  • Andi: having the infrastructure in place (license, domain) will bring us to a really good place.
  • Andi: we should write a short blog post about it, and tweet it on twitter to promote it. I think our blog posts are under utilised.
  • Lee: totally agree, I just haven't had the time. Write it, send it as a PR and we'll get it merged.
  • Donna: what's the repo?
  • Benjie (chat): https://github.com/graphql/graphql.github.io/tree/source/src/content/blog
  • Lee: automatically deployed as things get merged
  • Donna: so just a markdown file for someone to write a blog post
  • Lee: we don't put enough effort into sharing the results of the group, we should make a point to share more of them here.

Secondary meeting - EU

Agenda