Add AI meeting summaries (#1801)

Author: benjie

notes/2025/summary-2025-06-26.md

@@ -0,0 +1,67 @@
+# Meeting Summary for Working Group Meeting
+
+**NOTICE**: This summary was auto-generated by Zoom's "AI". AI-generated
+content may be inaccurate or misleading. Always check for accuracy. If in
+doubt, please consult the meeting recording at
+https://youtube.com/@GraphQLFoundation/playlists
+
+- Meeting start: 2025-06-26T17:30:08Z
+- Meeting end: 2025-06-26T19:04:12Z
+- Summary start: 2025-06-26T17:31:36Z
+- Summary end: 2025-06-26T19:04:10Z
+
+The GraphQL Working Group meeting covered several key topics, including updates to schema coordinates, reorganization of the specification, and discussions on various RFC proposals. The group reviewed and approved changes to improve consistency in schema definitions and addressed longstanding issues in the specification. Throughout the meeting, participants focused on aligning the specification with the reference implementation, GraphQL.js, and discussed the implications of proposed changes for future versions of the specification.
+
+## Next Steps
+
+- Mark: Update the schema coordinates implementation in GraphQLJS to handle meta fields appropriately and clarify behavior for schema coordinate resolution
+- Lee: Review and merge the schema coordinates PR after Mark's updates
+- Lee: Clean up and merge parts 1 and 2 of Benjie's data collections trilogy PRs
+- Lee: Review and simplify the data structures notation section at the top of the GraphQL spec before merging related PRs
+- Stephen: Update the descriptions on executable definitions PR to deduplicate text between sections 2 and 3, remove redundant definition, and rename section titles
+- Lee: Review Benjie's bug fix PR regarding spec text alignment with GraphQLJS implementation
+- Lee: Review Benjie's list coercion PR for algorithmic clarity and variable handling
+- Martin: Update GraphQLJS to alpha 9 for specified definitions appendix implementation
+- Stephen: Continue implementation work on object deprecation RFC and re-engage previous contributors for feedback
+
+## Summary
+
+### Schema and RFC Review Meeting
+
+Lee reviews the agenda for the meeting, which includes discussions on schema coordinates, specified definitions as a new appendix section, descriptions on executable definitions, editorial review for execution result, and several RFCs from Steven and Benjie. Benjie mentions the addition of a new RFC status for GraphQL WG. The meeting begins with introductions from attendees and a reminder to contribute to the notes document, especially for technical content that the AI note-taker might miss.
+
+### Schema Coordinates Proposal Updates
+
+The group discusses updates to the schema coordinates proposal. Mark reports that he has reverted to using dot separators for most elements except arguments, based on majority feedback. Lee recalls the rationale for previously blocking meta fields, but agrees they can be allowed. There is some discussion about edge cases with meta fields, which Mark suggests could be addressed with a clarification in the spec. Lee indicates that the main criteria for approval is having the code available, with the final decision on how to handle meta fields being the last outstanding item. Benjie raises a question about how to represent the schema coordinate for meta fields like __typename. The group considers whether it's realistic to include this in the July release, pending resolution of these final details.
+
+### Meta Fields in Schema Coordinates
+
+The discussion focuses on how to handle meta fields in schema coordinates. Lee explains that meta fields are not part of the schema but are special cases handled during execution. The group agrees that schema coordinates referring to meta fields should be syntactically valid but semantically null when resolved. They decide to add a note in the specification stating that resolving a meta field doesn't return anything. The implementation in GraphQL.js should mirror this behavior. The team also considers the possibility of introducing more specific handling for meta fields in future versions of the specification.
+
+### Type System Definition Reorganization
+
+Martin presents a proposal to group all specified type system definitions in a single appendix at the end of the specification. The group discusses the ordering of fields and directives in the spec, with Lee explaining that the current order is based on dependency, importance, and complexity rather than chronology or alphabetical order. There is some debate about where to place certain fields like "specifiedBy", but the group agrees that consistency between the spec text and GraphQL.js implementation is important.
+
+### GraphQL Pull Request Merge Discussion
+
+Lee suggests merging the pull request with minor changes, including removing modifications to introspection and updating to GraphQL.js alpha 9. Benjie proposes moving some fields to higher positions for better organization. The group agrees to make these changes and merge the pull request. Lee initially misunderstands the proposed changes but quickly corrects himself. The discussion then shifts to descriptions on executable definitions, with Stephen reporting that the spec edits and GraphQL.js implementation are nearly ready. The group considers moving this proposal to RFC 3 status, and Martin mentions that Apollo team members are excited about its potential for AI-related work.
+
+### GraphQL Descriptions Section Restructuring
+
+Stephen and Lee discuss reorganizing the GraphQL specification's sections on descriptions. They agree to move the main definition of descriptions from section 3 to section 2, making it a core language concept rather than just part of the type system. The section in 2 will be titled "Descriptions" and will cover descriptions more holistically, including their use in queries and schemas. Section 3.2 will be renamed "Type System Descriptions," with its content reduced to reemphasize the importance of descriptions in the type system and provide specific examples. They plan to remove duplicate grammar definitions and deduplicate text between the sections.
+
+### GraphQL Schema Deprecation Discussion
+
+Stephen plans to make changes to the GraphQL.js feedback revision and submit it. The group discusses the RFC for deprecation of objects in GraphQL schemas. They agree that everything in a schema should be deprecatable, and that removing deprecated elements should still result in a valid schema. Lee suggests adding an "includeDeprecated" parameter to the __schema field in introspection queries, which would allow clients to view either the full schema or a subset without deprecated elements. The group also discusses the implications of deprecating object types in unions and interfaces, acknowledging the need for a way to maintain these over time.
+
+### RFC Proposals and Data Collections
+
+The group discusses several RFC (Request for Comments) proposals and their progress. They accept and merge a proposal about not excluding the schema keyword if the schema has a description, noting that GraphQL JS already implements this behavior. They also review a set of three related pull requests about data collections, which Benjie wants included in the next spec release to improve accuracy and precision. Lee agrees to include these changes, marking them as accepted, but notes he will make some editorial simplifications before merging. The meeting concludes with a brief mention of additional linked pull requests related to the data collections proposal.
+
+### GraphQL Schema Consistency Improvements
+
+Benjie proposes three changes to improve consistency in GraphQL schema definitions. The first two changes are approved: one clarifies that fields should be returned in a consistent order when possible, and the other recommends maintaining order for unordered elements like enums. The third change, which explicitly marks certain schema parts as ordered, is set aside for further discussion due to potential implications for performance and implementation flexibility. Lee agrees to merge the first two changes.
+
+### GraphQL Specification Bug Review
+
+The group discusses two issues in the GraphQL specification. Benjie presents a longstanding bug in the spec that needs fixing, providing detailed spec text for Lee to review. They also address list coercion, which Benjie has rewritten to use a more algorithmic system and to better handle variables. Lee agrees to carefully review both issues, emphasizing the importance of aligning the spec with the reference implementation, GraphQL.js. The meeting concludes with Lee acknowledging the productivity of the session and the need to finalize the discussed changes.

notes/2025/summary-2025-07-03.md

@@ -0,0 +1,73 @@
+# Meeting Summary for Working Group Meeting
+
+**NOTICE**: This summary was auto-generated by Zoom's "AI". AI-generated
+content may be inaccurate or misleading. Always check for accuracy. If in
+doubt, please consult the meeting recording at
+https://youtube.com/@GraphQLFoundation/playlists
+
+- Meeting start: 2025-07-03T17:29:36Z
+- Meeting end: 2025-07-03T19:04:05Z
+- Summary start: 2025-07-03T17:31:15Z
+- Summary end: 2025-07-03T19:03:55Z
+
+The GraphQL Working Group meeting focused on reviewing recent specification updates and editorial changes, including discussions about request errors, operation execution, and meta fields implementation. The team evaluated various RFC proposals related to coercion algorithms, schema coordinates, and the handling of meta fields in GraphQL.js, with several members providing feedback on potential improvements and clarifications. The conversation ended with discussions about the implementation of experimental features like executeIncrementally and the handling of asynchronous iterators, with the team agreeing to maintain a general specification while allowing for implementation-specific details in GraphQL.js.
+
+## Next Steps
+
+- Lee: Complete final editorial review of the spec before the next cut
+- Lee: Review and finalize editorial changes for schema coordinates Meta field handling in the spec
+- Benjie: Create a more detailed proposal for execute Meta field algorithm with specific handling for __type, __schema, and __type Meta fields
+- Rob: Create a PR to update GraphQL.js regarding schema coordinate Meta field behavior
+- Rob: Continue work on the incremental delivery integration branch and merge approved sections
+- Lee: Review and polish pending changes for the next spec cut in the coming days
+- Benjie: Review Rob's pull request for section 3 spec edits regarding directive definitions
+
+## Summary
+
+### GraphQL Working Group Meeting Updates
+
+The GraphQL Working Group meeting began with Lee noting the thinner attendance due to the holiday week and introduced the agenda, which included updates on the spec, editorial changes, and several RFCs. Benjie highlighted the upcoming discount period for GraphQL Conference tickets and provided a summary of the previous meeting's progress, including merged items like executable descriptions and deprecation discussions. The group planned to discuss schema coordinates, argument values, list coercion algorithms, and incorporating Meta fields into execute collected fields, among other topics. Lee encouraged attendees to review the previous meeting's outcomes and emphasized the importance of highlighting upcoming dates to avoid scheduling conflicts.
+
+### Refining Error Classification in Specifications
+
+Benjie proposed changes to clarify the distinction between request errors and operation execution errors in the specification, focusing on terminology adjustments and editorial updates. Leebyron encouraged others to review the changes and expressed concerns about the placement of subscription-specific logic within the request execution phase, suggesting a need for further consideration of subscriptions' unique steps. Benjie acknowledged the complexity of subscriptions and considered creating a new algorithm but decided to maintain the current approach for now, aiming for a clean separation between request and operation execution phases.
+
+### Schema Meta Fields Implementation Discussion
+
+The team discussed schema coordinates and meta fields, with Mark and Benjie presenting a solution that defines implementation-specific behavior for unresolved meta fields. Leebyron expressed satisfaction with the current proposal, though he may refine the language to clarify the meta case further. The group agreed that the current specification is acceptable, with Martin suggesting the possibility of introducing resolving logic in future releases. The team also noted that the GraphQL.js implementation needs updating to reflect the new changes.
+
+### GraphQL Meta Fields Implementation Discussion
+
+The team discussed the specification of meta fields and their implementation in GraphQL.js. They agreed that meta field resolution should be left implementation-specific, with GraphQL.js currently returning virtual objects. Mark will update the JavaScript version to ensure it aligns with this approach. The team decided not to rush the specification cutoff date of July 1st, as most major changes have been merged and they are close to RFC 3. Leebyron will conduct a final editorial review, and Mark will submit a pull request to address the remaining issues.
+
+### GraphQL Schema and Coercion Discussion
+
+The meeting focused on discussing schema coordinates and meta fields, with Leebyron explaining that meta fields are not part of the schema and can be implementation-specific. Benjie highlighted the distinction between schema elements and introspection types, noting that introspection queries may include both schema and implementation-specific types. The group also discussed two RFCs related to argument value coercion in GraphQL, with Leebyron proposing a more significant rewrite of the algorithm to avoid relying on the "hasValue" concept. Benjie presented a coercion table for arrays and input objects, which aligns with GraphQL.js behavior and addresses underspecified areas in the current specification.
+
+### GraphQL Input Coercion Discussion
+
+Benjie and Lee discussed advancing a GraphQL specification for input coercion, particularly focusing on list coercion. Lee suggested not advancing to Stage 2 due to incomplete definitions for input object coercion, proposing instead to address the entire input coercion domain holistically. Benjie argued for prioritizing a more specific solution for list coercion to help implementations, with the possibility of a later refactor to address the broader input coercion problem. They agreed to proceed with the current draft for list coercion while exploring a more comprehensive solution in parallel.
+
+### Value Coercion Specification Discussion
+
+Leebyron and Benjie discussed the approach to handling value coercion in the specification, comparing it to the existing value completion algorithm. They agreed that a more algorithmic approach would be clearer than prose-based descriptions. Leebyron supported merging a fix for the "has value" bug into the current specification release, as it addressed an active issue rather than just clarifying ambiguity. They decided to mark this change as an RFC rather than an editorial update, acknowledging that it would change behavior in implementations.
+
+### GraphQL Specification Updates Discussion
+
+Leebyron and Benjie discussed recent changes to the GraphQL specification, focusing on clarifying the collection and execution phases. They highlighted a significant renaming and cleanup of variables, which Benjie had worked on, and encouraged others to review this change, especially those working on implementations like GraphQL.js or GraphQL Kotlin. Benjie also explained that he had added support for executing Meta fields in the specification, aligning it with the behavior in GraphQL.js, and avoided using undefined or null values to maintain consistency. Leebyron approved of these changes and suggested that the next steps involve further work on top of this updated foundation.
+
+### GraphQL Meta Fields Implementation Discussion
+
+The team discussed the placement and implementation of meta fields in the GraphQL specification. Leebyron and Benjie agreed that the current location in the spec is appropriate, as it correctly implements the behavior for meta fields. They decided that this change should move through the RFC phases quickly since it addresses a clear hole in the specification. The team also discussed the implications of meta fields returning complex types instead of simple strings, but ultimately decided to keep the implementation implicit rather than making it more explicit, as they felt it would unnecessarily complicate the spec. Leebyron concluded that this change should at least be RFC 1, as it clearly solves a problem in the specification.
+
+### GraphQL Meta Fields Discussion
+
+Lee and Benjie discuss two potential approaches for defining meta fields in the GraphQL specification. They agree to leave the current proposal as RFC1 and consider a more detailed alternative that defines the three meta fields and their behavior. Lee suggests that once they decide on the appropriate draft, it can likely move directly to RFC3 without needing GraphQL.js changes. Benjie notes that the implementation needs to be in the "execute collected fields" section. They also discuss where to place the new algorithm in the spec, with Lee preferring to keep it in the execution section.
+
+### GraphQL.js Incremental Execution Return Type
+
+The team discussed the return type of the experimental `executeIncrementally` function in GraphQL.js, focusing on whether to use a wrapper object or an async generator for incremental delivery results. Leebyron suggested keeping the spec general and implementation-specific, as the async generator and stream concepts are equivalent from an HTTP API consumer's perspective. Rob agreed to keep the spec description general, leaving the exact GraphQL.js implementation details to the mutators. Leebyron highlighted the benefits of the current type system, which unifies the path for operations with and without defers and streams, and suggested that the return type could evolve in the future to better align with these goals.
+
+### GraphQL Server Implementation Discussion
+
+The team discussed the implementation of GraphQL servers and the handling of asynchronous iterators, with Benjie expressing concerns about potential pitfalls for developers who might incorrectly handle map objects containing streams. Leebyron and Benjie agreed that while GraphQL.js should use a more specific type system to handle initial and subsequent results, the specification should describe it as a stream to maintain consistency across transports. Rob mentioned a pull request for editorial changes to section 3 of the spec, which Benjie agreed to review, and Leebyron encouraged merging changes into the integration branch at an early stage to facilitate the review process.