GraphiQL maintainer structure

[leebyron]

Hey all - I'm very excited to see a bunch more maintainers come in and a host of fantastic ideas. With this in mind, I want to make sure the GraphiQL project has the right maintenance and leadership structure in place so we can make sound decisions quickly, have a way to unblock any stalemates, and set up a plan.

Current active maintainers list curated via PR review process - last updated october 2021

This structure is a proposal, and I'd like feedback on this before rolling it out:

Tl;dr:

• A list of "maintainers" with merge rights, actively raising new ideas, decisions to make, writing reviewing and merging PRs relative to the project's plan.
• Amongst them, a small list (3-5) of "core maintainers" with decision making authority and accountable to determine a project plan.
• Amongst them, a single "lead maintainer" accountable to ensure decisions are made.

Core Maintainers

A fixed set of maintainers (at least 2, no more than 5, ideally 3-4), including the Lead Maintainer, accountable to come to consensus to determine the technical and product plans for GraphiQL.

This group does have the ability to make decisions. Essentially all hold "veto power" for decisions. This group should be willing to meet regularly and work together in good faith and try to find consensus.

Anyone can volunteer to join this group, the TSC will select the final group.

Lead Maintainer

This person would be accountable for the GraphiQL project's maintenance and forward momentum. Making sure decisions get made, that GraphiQL working group meetings happen and run smoothly, owning the agenda, and helping to unblock when necessary.

However, this person is not a unilateral decision maker - decisions get made by the Core group

The core maintainers collectively decide their lead via ranked choice.

Escalation

In the case that the project gets stuck, can't find consensus on a decision, or wants any other input - any core maintainer can ask for help from the TSC or myself.

---

Thoughts and feedback on this?

cc @timsuchanek @orta @acao @saihaj @Urigo @mjmahone @imolorhe @yoshiakis @graphql/tsc - but all are welcome to weigh in

[timsuchanek]

That suggestion makes a lot of sense to me!
Once that core group is decided, a good next step can be to look at the WG meetings, if we want to keep the current cadence or do adjustments where we see fit. And I think once we even have a partial agreement for a plan, we'll be able to pick up more momentum again.

[saihaj]

So we are back to every second Tuesday of month schedule? I think we need to make agenda updated always and post it in advance :) if we are not doing a meeting we can just update the file to say canceled or moved for consistency.

[acao]

@patrick91 would probably agree with this!

[acao]

@cshaver and I have been recording ad-hoc pairing sessions as well, and adding minutes for them, which we've been using to plan architecture for projects like monaco-graphql, which we could still advertise a few days ahead of time. Should we be reporting back major change proposals to the WG or the TSC or who then? Where should we keep our minutes? Should we try to regularize the schedule so that more can attend?

For example, we plan on re-architecting the schema loading pattern to use indexeddb to make schema editing better, improve the web worker lifecycle and make multi-editor editing more performant. Where should we propose that change in this new structure I wonder? Or is that an internal detail that doesn't require as much review?

Similar recorded pairing/design planning sessions could occur for the LSP server and vscode-graphql, quite fruitfully! @orta what do you think?

[timsuchanek]

Agreed @saihaj! That's what I just started - posted the agenda beforehand for the WG that happened this week. The meeting is also in the GraphQL foundation calendar. Unfortunately only @acao and I showed up, so I think we need to work on the visibility for that. I for example didn't see a WG happening in Oct.

@acao we'll need to find the waterline for which decisions PR reviews are fine, when we want a WG meeting and when to involve TSC. Generally, I'd only involve TSC if consensus can't be found within the group or the change would have wide-reaching effects.

For the suggestion of including indexeddb, for that I'd first try to find consensus between the core maintainers and then when it can't be found, move that to TSC if needed.

Should we try to regularize the schedule so that more can attend?

Can you elaborate on what you mean by regularize?

[leebyron]

Generally, I'd only involve TSC if consensus can't be found within the group or the change would have wide-reaching effects.

Definitely agreed.

I think reporting back semi-regularly to the WG (this is the right live forum for TSC) would be beneficial and welcomed. Both to source input on direction (ex: collecting feedback on new design) and give general updates.

That said, my hope in setting up some structure is to give the graphiql project a reasonable amount of autonomy to make decisions and move forward. If the core maintainers feel a direction is correct with consensus and confidence then there's no need to get approval elsewhere. If direction/decisions lack consensus or confidence then you can always lean on the TSC (via WG meetings) to gather more input or look for a decision

[acao]

This is a great proposal overall! One additional thing we might need to account for, to make maintainer onboarding a little less overwhelming, is to expect some degree of domain focus for most core maintainers at least at first.

The concerns of the LSP server side vs the monaco-graphql side vs the graphiql side of things can be a wide scope for any one person to make decisions for. but 3-5 should be enough to account for that dynamically.

The dual project roadmaps of the end reference implementations graphiql and vscode-graphql can readily drive the decision making processes, and scoping efforts more democratically

[acao]

So much could be discovered in the process of triaging issues across graphiql and vscode-graphql process, and once de-duplicated, renamed issues can serve as the roadmap items to drive the process, to show that we are honoring long-awaited feature requests in various capacities. The graphiql users themselves have a plethora of good ideas here already! potential-plugin, enhancement labels and the github projects beta roadmaps can serve as starting point to find these tickets that might warrant roadmap placement, but there are likely many not labelled still. There might be some that are even closed that are worth revisiting.

[acao]

The most useful domain distinction is between graphiql roadmap and the vscode-graphql roadmap. Almost all of the efforts in this repository could be aligned to these two reference implementations, and documentation, examples, etc. the LSP CLI is also an important reference implementation service layer to maintain.

Improvements to graphql-language-service would benefit all runtimes, but these are less frequent, though there are some waiting that would be so magical (for example, autocompletion of type field names & matching types from schema for implemented types/interfaces )😍

[orta]

👋🏻 not too sure if I can realistically commit to regularly attending working groups, my spare time for OSS is split up enough between commitments to TypeScript/Twoslash/CocoaPods/Danger + longtail OSS - but I can help out as a maintainer on the repos and occasionally pop into WGs when someone wants me more directly (like is happening now)

[timsuchanek]

Unless anyone objects, it seems like we're good to move forward with @leebyron's proposal.

@leebyron how could we move this forward from here?
One proposal: We could decide this in the next WG meeting on the calendar, April 12th. (we'd nee to make sure everyone who wants to be a core maintainer needs to join that meeting)
Moving this forward async is of course also an option.

[dpnova]

I was thinking about this earlier, I wondered if the monorepo with several fairly disparate tools is intimidating to new comers who may be interested in contributing to only one of them? The list of issues is huge and seems insurmountable, but would probably be considered more reasonable if things were broken up.

I've noticed an effort to consolidate a few projects here, so maybe the benefits of doing that outweigh any negatives.