GIP-0061: Improvements to the GIP process (WIP) #30

pcarranzav · 2023-09-28T21:18:47Z

Early draft of some proposed changes to GIP-0001 and GIP-0001, with an accompanying GIP-0061 explaining the rationale for the changes.

gips/0000-template.md

gips/0001-gip-process.md

p-diogo · 2023-09-29T10:30:00Z

gips/0001-gip-process.md

+
+Once a GIP is published on the GitHub repo and the forum, some time should be left for the community to discuss. Some more complex or controversial proposals may require more time and discussion, while others that are more straightforward may be accepted more quickly, always at the Council's discretion.
+
+After publishing, the authors are encouraged to present the GIPs in one or many of the relevant community calls, for instance, Indexer Office Hours that happen weekly on Discord, or the monthly core developer calls. To request a speaking slot in one of these calls, you can use this form (TODO: add form link) to get in touch with organizers from core dev teams and The Graph Foundation.


@pcarranzav, @dmachotka and I will propose a form link for people to get in touch

gips/0001-gip-process.md

p-diogo · 2023-11-28T12:02:54Z

gips/0001-gip-process.md

+
+**To avoid conflicts in GIP numbers, proposals should be posted as a Pull Request on GitHub with a GIP number _before_ being posted to the forum**.
+
+After creating the Pull Request, post a thread in the GIPs and Governance category with a link to the Pull Request. The post should have the same title as the GIP, and include the Abstract and Motivation sections but linking to GitHub for the full GIP text. (Older GIPs may include the full proposal text in the forum post, but this is now discouraged as it is hard to keep the forum and GitHub versions in sync).


@pcarranzav with the new GIP Tracker, we're considering having a GPT-powered TLDR/Summary for all GIPs, so people can quickly understand what the whole proposal is all about without having to read the entire thing (after clicking a link from the forum). It might make sense for us to do the same in the Forum discussion for all subsequent GIPs, with some automation. Do you see any problem with this?

I think that'd be pretty cool! I would just suggest adding a disclaimer noting this is a GPT-powered summary so it might be biased

RembrandtK · 2024-08-06T10:48:03Z

Subproposal to consider as part of this: Should we consider changing GIP filenames (and therefore the URL) to exclude the name?

For example instead of 0001-gip-process.md use 0001.md?

Examples of how done elsewhere, demonstrating the pattern:

Advantages:

GIP can be easily looked up by URL (https://github.com/graphprotocol/graph-improvement-proposals/blob/main/gips/0001.md), without knowing or needing to type (or otherwise encode) the title.
The title can be changed without breaking links.
There is no ambiguity what the filename should be. (I see different variations of how to encode the title.)
There is one authorative source for the title, what is specified in the file, rather than multiple versions.

Disadvantages:

You cannot tell what the GIP is about just by looking at the filename.
This is a change from what we are currently doing. (Bias to not changing unless there is a good reason.)

On balance I think the change will not be too disruptive (we might decided to leave historical GIPs 'as-is' to avoid breaking existing links) and worth doing. Not including the filename is the norm elsewhere.

Thoughts?

Additionally, we should consider configuring GitHub pages to provide GIPs links showing just the GIP, rather than wrapped in GitHub navigation and context.

RembrandtK · 2024-08-06T10:54:02Z

And, while I think of it, I would be tempted to setup GitHub action requiring MD files pass MD lint tests. I have not checked if this is a good one, but as an example: https://github.com/marketplace/actions/markdown-lint

RembrandtK · 2024-08-06T11:00:52Z

Another comment. :) I just got access to the GIP Tracker. That seems to be a manually maintained table? Could an automated version be created? Using GitHub action we could automatically create an index with the relevant information?

p-diogo · 2024-08-07T09:02:00Z

@RembrandtK , thanks for all these suggestions.
I do see value in some. My take:

Set up CI with MD lint tests: I agree; nothing is controversial here.
On the more public-friendly Notion-based GIP Tracker: we plan to revamp it fully and have a better UI and navigation system. As we will stick with Notion, I agree we should automate it.
Removing the GIP title from file name (and URL): I only find it useful to have the name in the .md file if navigation is based on GitHub-hosted GIP files. Given we'll have a better GIP Tracker and that we can indeed consider start using GitHub pages instead (will need some testing), I think we can go forward with your proposal and be more aligned with what seems to be the norm.

I unfortunately don't have the time to test all these proposed changes, but the Foundation will very soon have a new collaborator that will own governance end-to-end. Updating the GIP process and merging this PR will be that person's top priority. 👍

Andrew-Clews

I've added my changes. As a next step @pcarranzav please double check my comments and I will directly update proposed changes.

Andrew-Clews · 2024-09-12T19:09:24Z

gips/0000-template.md

 Title: <The title of this GIP>
 Authors: <A list of authors. Include full name or pseudonym. At least one author must have valid contact information provided in angle brackets.>
 Created: <The date the GIP was created.>
-Updated: <The date the GIP was last updated.>
-Stage: <The current stage of the proposal. Specified by the author and confirmed by editors by virtue of a GIP being accepted into an editor's view of the repo.>
+Stage: <The current stage of the proposal. Specified by the author and confirmed by editors by virtue of a GIP being accepted into the main branch of the GitHub repo. See GIP-0001 for the possible stages and process.>
 Discussions-To: <The forum post where this proposal is discussed.>
 Category: <(Optional) The type of GIP or GRP. This field should be left blank for GRCs. Valid types are "Protocol Logic," "Protocol Interfaces," "Subgraph API," "Process," "Economic Parameters," and "Protocol Charters".>


This line refers to GRP which I believe will be removed going forward. Should this reference be removed?

Andrew-Clews · 2024-09-12T19:12:21Z

gips/0001-gip-process.md

 Created: 2021-02-21
-Updated: 2021-04-09
+Updated: 2023-09-28
 Stage: Living
 Discussions-To: https://forum.thegraph.com/t/gip-0001-and-getting-started-with-gips-grps-grcs-etc/1722/4


Does it make sense to also point to this link? https://forum.thegraph.com/t/gip-0061-improvements-to-the-gip-process/4570

Andrew-Clews · 2024-09-12T19:13:20Z

gips/0001-gip-process.md

@@ -35,80 +35,138 @@ The high-level process is captured in the diagram below.

 ## Before a proposal is written

-The author(s) should do the leg work to assess whether their idea is a good one that is likely to be supported by the community. This includes discussing the idea in public formus such as Discourse, Discord and Twitter.
+The author(s) should do the leg work to assess whether their idea is a good one that is likely to be supported by the community. This includes discussing the idea in public spaces such as [Discord](https://discord.gg/graphprotocol), [Twitter](https://twitter.com/graphprotocol), and [The Graph forum](https://forum.thegraph.com/).

 The author should also make sure the proposal is in line with the values and mission of The Graph. This may include reading past blog posts that allude to The Graph's design philosophy as well as talking to existing contributors to The Graph.


Is there a page or source that spells out the values and missions of The Graph that could be used as a point of reference?

Good question, the closest I could find that is public facing is this: https://thegraph.com/blog/introduction-to-the-graph/ - but there may be others or we may want to publish something updated and more thorough

Andrew-Clews · 2024-09-12T19:15:10Z

gips/0001-gip-process.md

- Brandon Ramirez
- Jannis Pohlmann
+- Michael Macaulay
+- Pedro Diogo


Should we provide a method of contact on how to reach the editors?

I think the same Form we're using for other things should work?

Andrew-Clews · 2024-09-12T19:18:01Z

gips/0061-improved-gip-process.md

+
+## Simplified Stages
+
+The Strawman and Proposal stages have been removed and merged into the Draft stage. In practice, proposals evolve from a simple abstract to a full blown spec, and tend to change throughout the process, and it's hard to draw the line between different stages. Keeping the stage updated in the GIP takes time, so we believe it's simpler to just differentiate between a proposal that is in progress ("Draft"), one that is ready for acceptance/deployment ("Candidate"), and one that has been concluded ("Accepted/Deferred/Withdrawn/Living").


The original stage was referred to as Strawperson. Should this be updated to reflect the original term used?

Ah, Strawperson rather than Strawman? Good catch, missed it

Andrew-Clews · 2024-09-12T19:29:11Z

gips/0001-gip-process.md

-4. **Candidate.** A proposal at this stage has a reference implemenetation that has been linked in the document and can be used to validate the idea described in the protocol.
-5. **Accepted | Deferred | Withdrawn | Living.** These are resolution stages for a proposal:
+1. **Draft.** This stage encompasses all proposals that are not ready for deployment. The proposal might include just Abstract and Motivation, or have a full-blown Detailed Specification. It can evolve through community feedback when in this phase, and the key requirement to move to "Candidate" is to have an implementation that is ready for deployment.
+2. **Candidate.** A proposal at this stage has a reference implementation that has been linked in the document and can be used to validate the idea described in the protocol. The implementation must be ready for deployment, having completed any relevant audits and test plans.


After reviewing the stages here, please consider the following categories and associated definitions as they may enhance GIP tracking going forward:

Draft - Day 0 through to Candidate stage

Candidate - The Author may move their GIP to the candidate stage in Github to indicate to the Council and to the public that they believe enough support has been gathered from the community and sufficient due diligence has been completed for the Council to make a decision for approval. A minimum of 1 week draft on forum for public review is required.

Approved - Council approval has been obtained for the GIP

Deferred - The GIP is on hold or otherwise working through remediations to obtain Council approval

Withdrawn - The submission was withdrawn by the Author or was withdrawn due to Inactivity. If more than 6 months have elapsed with no activity editors may move the status of a GIP to withdrawn. Authors may still contact editors to re-activate their proposal if the Author would still like to proceed with their submission at a later date.

Implemented - Indicates that a GIP has either been deployed in the case of a code change or is in use today for procedure changes or other non-code based changes.

I have also started using 'Reserved', for GIP numbers that are reserved for future use but might not have any details associated yet. This is an optional stage before 'Draft'. If necessary or simpler they could have 'Draft' status and state they are reserved in the text.

I like the idea of adding an "Implemented" stage.
And for simplicity @RembrandtK I would suggest just using Draft, rather than adding an additional stage for Reserved.

For clarity it would be good if we outlined the "happy path" first, i.e. Draft-Candidate-Approved-Implemented, and then separately mention the other possible states (Deferred/Withdrawn), so that readers can get a general idea of the usual flow and then learn about the "exceptions". Wdyt?

Agreed, we should present Deferred and Withdrawn after the natural progression of stages. I also agree having one stage for draft reduces complexity without losing effectiveness.

Updated the Category field to remove a reference to GRP.

Added additional "Discussions-To" link to more recent forum post. Added link to new intake form wherever TODO was noted. Updated the GIP stages and descriptions.

Updated the Discussion-To portion of the form with the relevant link to the forum. Changed the Strawman reference to Strawperson to reflect the original language used.

RembrandtK · 2024-12-09T09:49:08Z

Are we ready to push updates? What would it take to get updates made this year?

Even if more are coming, would be good to capture some of this. I am finding I have to come to this PR for reference, knowing that it exists, because main versions do not have the information I need or out of date.

RembrandtK · 2024-12-09T09:49:13Z

Separate topic, worth noting it seems many GIP status are out-of-date, worth a historical cleanup? (If doing that, would be good to have lint tests live and do lint fixes during the process.)

GIP-0061: Improvements to the GIP process (WIP)

07f8b71

p-diogo reviewed Sep 29, 2023

View reviewed changes

gips/0000-template.md Outdated Show resolved Hide resolved

p-diogo reviewed Sep 29, 2023

View reviewed changes

gips/0001-gip-process.md Outdated Show resolved Hide resolved

p-diogo reviewed Sep 29, 2023

View reviewed changes

gips/0001-gip-process.md Outdated Show resolved Hide resolved

p-diogo reviewed Sep 29, 2023

View reviewed changes

gips/0001-gip-process.md Outdated Show resolved Hide resolved

pcarranzav added 4 commits September 29, 2023 15:14

fix: comments on the PR from Pedro, and a couple details

33e16df

chore: add flowcharts

d1c8665

fix: one form to rule them all

c775ac0

fix: typo

5316999

pcarranzav mentioned this pull request Nov 9, 2023

Create XXXX-optimizing-query-fees-sent-to-indexers.md #33

Merged

p-diogo reviewed Nov 28, 2023

View reviewed changes

Andrew-Clews reviewed Sep 13, 2024

View reviewed changes

Andrew-Clews added 4 commits October 10, 2024 09:23

Remove GRP Reference 0000-template

43c9765

Updated the Category field to remove a reference to GRP.

0001-gip-process: added missing links, revised GIP stages

5b23baa

Added additional "Discussions-To" link to more recent forum post. Added link to new intake form wherever TODO was noted. Updated the GIP stages and descriptions.

0061-improved-gip-process added forum link, strawperson reference

cf8e2fe

Updated the Discussion-To portion of the form with the relevant link to the forum. Changed the Strawman reference to Strawperson to reflect the original language used.

Merge branch 'main' into pcv/improved-gip-process

4cb42f3

RembrandtK mentioned this pull request Nov 30, 2024

GIP-0081: Indexing Payments #59

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GIP-0061: Improvements to the GIP process (WIP) #30

GIP-0061: Improvements to the GIP process (WIP) #30

pcarranzav commented Sep 28, 2023

p-diogo Sep 29, 2023

p-diogo Nov 28, 2023

pcarranzav Nov 28, 2023

RembrandtK commented Aug 6, 2024

RembrandtK commented Aug 6, 2024

RembrandtK commented Aug 6, 2024

p-diogo commented Aug 7, 2024

Andrew-Clews left a comment

Andrew-Clews Sep 12, 2024

pcarranzav Oct 1, 2024

Andrew-Clews Sep 12, 2024

pcarranzav Oct 1, 2024

Andrew-Clews Sep 12, 2024

pcarranzav Oct 1, 2024

Andrew-Clews Sep 12, 2024

pcarranzav Oct 1, 2024

Andrew-Clews Sep 12, 2024

pcarranzav Oct 1, 2024

Andrew-Clews Sep 12, 2024

RembrandtK Sep 13, 2024

pcarranzav Oct 1, 2024

Andrew-Clews Oct 1, 2024

RembrandtK commented Dec 9, 2024

RembrandtK commented Dec 9, 2024


		Once a GIP is published on the GitHub repo and the forum, some time should be left for the community to discuss. Some more complex or controversial proposals may require more time and discussion, while others that are more straightforward may be accepted more quickly, always at the Council's discretion.

		After publishing, the authors are encouraged to present the GIPs in one or many of the relevant community calls, for instance, Indexer Office Hours that happen weekly on Discord, or the monthly core developer calls. To request a speaking slot in one of these calls, you can use this form (TODO: add form link) to get in touch with organizers from core dev teams and The Graph Foundation.


		To avoid conflicts in GIP numbers, proposals should be posted as a Pull Request on GitHub with a GIP number _before_ being posted to the forum.

		After creating the Pull Request, post a thread in the GIPs and Governance category with a link to the Pull Request. The post should have the same title as the GIP, and include the Abstract and Motivation sections but linking to GitHub for the full GIP text. (Older GIPs may include the full proposal text in the forum post, but this is now discouraged as it is hard to keep the forum and GitHub versions in sync).


		## Simplified Stages

		The Strawman and Proposal stages have been removed and merged into the Draft stage. In practice, proposals evolve from a simple abstract to a full blown spec, and tend to change throughout the process, and it's hard to draw the line between different stages. Keeping the stage updated in the GIP takes time, so we believe it's simpler to just differentiate between a proposal that is in progress ("Draft"), one that is ready for acceptance/deployment ("Candidate"), and one that has been concluded ("Accepted/Deferred/Withdrawn/Living").

GIP-0061: Improvements to the GIP process (WIP) #30

Are you sure you want to change the base?

GIP-0061: Improvements to the GIP process (WIP) #30

Conversation

pcarranzav commented Sep 28, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RembrandtK commented Aug 6, 2024

RembrandtK commented Aug 6, 2024

RembrandtK commented Aug 6, 2024

p-diogo commented Aug 7, 2024

Andrew-Clews left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RembrandtK commented Dec 9, 2024

RembrandtK commented Dec 9, 2024