TSC Discussion: Community Specs repository

[benjie]

Hi @graphql/tsc (and @graphql/tsc-emeriti); I'd like to propose a new repository: graphql/community-specs (and associated web address)

This repository would have a folder per "community spec" and can be edited by the community. Each spec would have a status (much like standard RFCs: strawman, proposal, draft, published), but would not (I think?) require the legal overhead of our current GraphQL Spec releases - these are not "project deliverables".

Community specs would include things like:

• Cursor connections spec
• Mutation Input Object spec
• Global object identification spec
• @semanticNonNull spec
• @matches spec

@captbaritone and I have been discussing something like this for the Relay specs, but chatting with @magicmark really surfaced that this is a strong need - see #1874 (comment)

I'll talk with @jorydotcom about the legal ramifications of having such a repo (I don't anticipate there being any problems); but wanted to check your thoughts first.

The repo should auto-build and auto-deploy each project using spec-md to generate a subpath (ideally versioned!) for each spec.

These specs would not necessarily be limited to GraphQL Spec related things; they might relate to the GraphQL-over-HTTP spec or the composite schemas spec, or just to general schema, usage, or modelling patterns that people find useful.

WDYT? Do we want a governance model for this? Should we namespace them like the scalars project, or not? (I'm leaning towards making these a little more "official" and thus requiring a bit more process, but not as much process as the main spec.)

[martinbonnin]

Neat! That'd bequite useful. I think the scalars set a good precedent there.

My preference goes to namespaced (like scalars) so we can move fast (no process besides merge checks), with 2 small twists:

• Mandatory versioning so we can filter out the obsolete specs from the main page (they remain accessible, just they don't clutter the main index page)
• A first-party graphql top-level namespace that promotes good quality specs with a small process (review window + a certain number of TSC approvals)

[martinbonnin]

Another interesting precedent in addition to scalars.graphql.org and the relay specs, is specs.apollo.dev.

It contains a spec for @semanticNonNull for an example and it has served us well in the past.