Suggested Changes for Improving the FIPs Process #215
Replies: 14 comments 14 replies
-
|
tl;dr - More and more people are engaging with FIPs, which is amazing!! But, we need to organize ourselves better so that we can scale the FIPs process in a clear and transparent way. Let's create dedicated spaces for each component of the FIPs process (Discussion Forum for ideas, Issues log ONLY for FIP Drafts, and PRs only for completed FIPs in Last Call status) so that it's easy to find and track proposals. |
Beta Was this translation helpful? Give feedback.
-
|
Link to Slack discussions: #fil-fips |
Beta Was this translation helpful? Give feedback.
-
|
Fantastic analysis of the current workflow, thank you! I support your proposal as an improvement well worth trying. |
Beta Was this translation helpful? Give feedback.
-
|
My initial impression is that overall this makes sense. Not sure about the UI/UX of GitHub Discussions, but could be good to have a space for ideas vs refining drafts. Since everything else FIP related is here the Discussions tab seems like the most natural fit rather than a separate platform, but the UI of the Discussions is a bit hidden so people will need to know to look for it. If the README points people in the right direction it's probably fine. At the PR stage, an explanation as to why a FIP was accepted or rejected could provide more transparency into the decision making process. This could be useful for individual proposals, but in a broader sense it might also help stakeholders understand the goals and concerns that are weighed when deciding on FIPs. Beyond that, if the Discussion, Issue, and Core Devs Call where the FIP was discussed were linked to in the final PR that could improve governance UX by making it easier for people to find information around a proposal to better understand the thinking behind it. This could help people understand how the system got to where it is today, which could help them understand where it might be going (vs just seeing a snapshot of the current state). |
Beta Was this translation helpful? Give feedback.
-
|
Great feedback, thanks @burrrata! I agree that the UI is a bit limited. This is the case with any platform, but I want to note that I also explored hosting a FIP Forum on another platforms (esp. Discourse, Matrix, and a separate FIPs landing page with a native forum feature built in). However, Github Discussions seemed the best due to the fact that so much ongoing technical work is already hosted here. There was also concern that hosting a separate space for ideas on a non-Github platform, but then asking folks to formally propose and work on FIPs within Github, may reduce the number of ideas that actually get worked on. In regards to the PR stage, I'd like to note that there is no one person who decides that a FIP is or is not accepted. Rather, a FIP becomes accepted once it has been audited for security and cryptoeconomic vulnerabilities, deemed technically feasible by the core devs team, and once it has transited through Last Call status with 1) a majority of community in support, and 2) no outstanding and/or unresolved questions/concerns about the impact and effect of the FIP itself upon the Filecoin network. However, I agree that much more documentation is needed to more deeply clarify this process, and it's an immediate goal! |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for getting this going @kaitlin-beegle , def support it! One suggestion would be, for
The issue is not the vest place for collaborative edits, where in PRs we can leave comments, suggest edits, and so on. So I personally think we should keep allowing to "keep updating FIP draft in PRs". |
Beta Was this translation helpful? Give feedback.
-
|
Would be great if we have some high-level guidelines on |
Beta Was this translation helpful? Give feedback.
-
|
^ yes, given the current immensity of the Issues log, the labels are a mess! We can improve these once the process more organically unfolds and we see what ends up in Issues. Re: PRs, yes, Kuba pointed this out too. I'll respond to this on his below post, and would love your help thinking through this |
Beta Was this translation helpful? Give feedback.
-
|
Great proposal, I agree and support this proposal! It makes sense to separate the Idea*-stage from the Draft-stage, but I +1 @burrrata point, that the Discussion UI on Github can be a bit hidden. Maybe new ideas with a link to the Github-discussion should be broadcasted to a Slack-channel as well (As long as it does not get too spammy)? |
Beta Was this translation helpful? Give feedback.
-
|
Yep, completely agree! I'll update the description in the #fil-fips Slack channel, and will continue to update guidance as well. Thinking about adding the updated FIPs workflow to docs.filecoin.io as well... |
Beta Was this translation helpful? Give feedback.
-
+1 to @burrrata why and how are great to have. |
Beta Was this translation helpful? Give feedback.
-
|
Got it! What do you think about creating a 'retro doc' for each network upgrade, including a rationale for the inclusion of each FIP? Because FIP acceptance requires multiple components, we could track (in the FIPs discussion repo) how each FIP is moving towards network acceptance, which processes and approvals are outstanding, etc.? Then, once everything is complete, it could be formalized in a single place. |
Beta Was this translation helpful? Give feedback.
-
|
How will we handle links to current backlog issues in the discussion phase? Want to make sure we have a smooth transition for ideas still in brainstorm phase (now and in the future as folks continue to start conversations that don't move out of buy-in gathering phase) |
Beta Was this translation helpful? Give feedback.
-
|
Yup yup! This might be a bit clunky at first, but (effective immediately) I'll begin asking authors to re-open backlog items with a link to any original conversations that may have taken place. Although its not ideal to have to link conversations across different spaces, this was also how many early FIP issues were debated within the Issues log itself (for ex., multiple different posts discussing various components of a single proposed enhancement, etc.) and community members seemed to navigate it effectively. Also, if I don't hear back from post authors relatively quickly, I'll just move the item myself, and provide all of the linking to original issues. |
Beta Was this translation helpful? Give feedback.
-
|
This is sound process improvement @kaitlin-beegle, we need to convert viable issues into change in a timeframe where they dont lose relevancy |
Beta Was this translation helpful? Give feedback.
-
|
Thanks @MegTei, completely agree!! We just had our final presentation of the process changes- this week's European Storage Provider Working Group meeting- and are beginning the process of moving items from the Issues log to the Discussion repo. I am going to ask original post authors to move their own content, so they can remain 'owners' of a conversation topic, but will move it manually if they're not responsive. Regardless, you should see items begin to move over in today and most things (if not all) should be moved into the Discussion Forum by the end of this week! |
Beta Was this translation helpful? Give feedback.
-
|
I feel there is a value of FIP existing as a FIP document in the repo before the Last Call stage, it allows for cooperative editing and authorship of FIPs, which is something that issues don't provide. The FIP Draft as an issue enforces that there has to be only one primary FIP author, I disagree with this, it should be possible for anyone to propose changes to a FIP and have these changes be evaluated by the community. The original author of the FIP can even "disappear" or stand aside and the community should be able to proceed with the same FIP (edit it), which will be much harder if FIP drafts are issues. In my opinion, discussion of changes to a FIP, review comments and version history are all essential parts of the process of evaluating complex changes to a complex system and improving them. See for example EIP PR for a minor change to EIP1559, ethereum/EIPs#2924 I think that if we expect the draft to be edited in a significant way after the discussion starts, then we should not use a medium that doesn't preserve history and I fully expect drafts to be edited in significant ways. |
Beta Was this translation helpful? Give feedback.
-
|
++ |
Beta Was this translation helpful? Give feedback.
-
|
Hey @Kubuxu! Thanks for taking the time to leave detailed feedback. This is very helpful, and I think your perspective highlights one of the fundamental trade-offs with using Github for the broader FIPs process: access to detailed version histories and edits, versus higher-level process organization. One of the primary challenges we have now is that the work happening in PRs is usually rather granular, and it's difficult for community members who aren't deeply involved in writing and reviewing FIPs to understand what's going on. The original idea, here, is that all work (including technical specs) would happen in designated branches, which do offer version histories. FIP authors (who can be numerous; just as one person opens a PR, but the header of the FIP can indicate multiple authors, so too could this be done in Issues) would be required to denote in which branch they are storing FIP -relevant information, and it would be this branch that would be pushed to the repo during 'last call'. Because work would be happening in repo branches, it could also be carried forth even if the original author was no longer committing changes or participating in the overall process. I wanted to first highlight this part of the proposed workflow to be sure that it was clear. That said, if you feel like this is not an adequate way of managing the complexities of FIP development (and I'm sympathetic to the fact that the purpose of Github is version histories and collaborative work) then we could modify the workflow so that items end up as a PR earlier in the process. We would then have to maintain a separate issue, which would provide high-level details about the purpose and scope of the FIP, so that the FIP workflow could still be organized and transparent. My primary interest is in moving us a way from a structure where FIPs of different scopes and complexity levels sit as PRs for different periods of time, with technical feedback coordinated in the PR and community feedback happening in the Issue, and no clear way to differentiate ongoing review from a nearly -complete FIP draft. I think the best way forward would be to enact the changes as presented, since it would be easy to revert to opening up PRs if we felt it was necessary. We should also (explicitly) redefine how long 'last call' may be, and/or add a second stage (technical review?) between Issues and 'last call' status so that we can push FIPs into a PR sooner. Where the FIP process generally differ from the EIP process is in the 'gating' that happens in their process, i.e., stages of review, feedback, and proposal development are more strictly defined and managed, and ours is more organic. Perhaps we also need to move towards more rigorous review components in order to balance the trade-off between complex technical work and general community buy-in and engagement. Regardless, your concern is important and rather fundamental to the spirit of the changes, so I'm eager to hear what you and @jennijuju think. |
Beta Was this translation helpful? Give feedback.
-
|
thanks Kaitlin, for the detailed write up! To collaborate and work on the same branch, with comments, reviews and history track would require authors to open PRs against that branch, which would be the same process as we do it today. |
Beta Was this translation helpful? Give feedback.
-
|
I think I had initially misunderstood some details in the original proposal, unsure how the terminology of "issue" was being used, since a GH PR is a type of issue under the hood.
I concur with @Kubuxu that this is too late. I'm still very keen for the pre-draft discussion to move out of the GH issues log and into the discussion forum, but once a first draft of a FIP document is ready, I agree it should be PRed to this repo immediately to open the discussion about the document and it's specifics (as opposed to the idea and its alternatives, which remain in discussion forum). So, it should be fairly common that the first PR for a FIP lands it in DRAFT stage, and subsequent PRs improve it until LAST CALL. But the goals here can still be supported. WIP ideas should be in the discussion forum. I would expect that every GH tracking issue for a FIP is preceded by by a discussion thread, and thence every PR point to that tracking issue for Discussion-To. We should have a high standard for completeness of FIP drafts and swiftly reject Issues/PRs that have not had sufficient prior discussion or do not contain enough detail for implementers, miners, clients etc to evaluate the proposal. I think we can retain the property that open issues and PRs track only proposals that are being actively worked toward. We should close down tracking issues that go stale, etc. |
Beta Was this translation helpful? Give feedback.
-
|
Heard loud and clear. I think updating the proposed workflow to the below will 1) satisfy concerns about making changes in PRs, 2) still provide clearer differentiation between FIP statuses.
With these updates, I think about the Issues log as a public notice board for FIP statuses and resources. Individual authors/teams can use the Discussion Forum however they'd like (if at all), and can merge and request changes in PRs whenever they'd like. However, the Issues log reports active FIPs in a consistent way, using relatively consistent formatting, and would be required for any FIPs that are actively being worked on. |
Beta Was this translation helpful? Give feedback.
-
|
I think there is a value to merge draft or at least last call FIPs to merge into the repo. |
Beta Was this translation helpful? Give feedback.
-
|
I see what you're saying, but I think this is one area where intention doesn't translate well to practice. We currently merge FIP drafts and it doesn't do much but create confusion about FIP statuses, where feedback can be left, and where work is being conducted. We also don't have concrete plans or an obvious use case for the FIPs website at the moment, so I don't think we need to worry about taking this into consideration right away. |
Beta Was this translation helpful? Give feedback.
-
|
Another suggestion is that CryptoEconLab should have more interactions with FIP issues not just the FIP issues by themselves but by the community too, as many FIP would have token economic implication for the network and the community needs guidance to align their FIP with goals of CryptoEconLab. Right now we don't see as much community involvement from CryptoEconLab compared with the time during mainnet launch. |
Beta Was this translation helpful? Give feedback.
-
|
One pain point im having with this new process, in which FIP Drafts are not merged until |
Beta Was this translation helpful? Give feedback.
-
|
I don't think we should hold off merging the FIP document until last call. We should merge large ones in draft. |
Beta Was this translation helpful? Give feedback.
-
|
Heard! And, agreed. |
Beta Was this translation helpful? Give feedback.
-
Problem
FIP0001 is the founding document for Filecoin network governance. It codifies the FIPs process, which is the primary mechanism of governance within the Filecoin ecosystem.
Currently, FIP0001 functions more like a charter than a process document or constitution. Although it technically outlines the types of FIPs and their requirements, its terminology and work flow have not kept pace with the manner in which the Filecoin community actually engages with governance.
As a result, stakeholders understand and use the FIP process in different ways, generating confusion. This confusion exhibits itself as:
The purpose of this document is to recommend a new FIP workflow that aligns the intent of FIP0001 with the actual FIP process workflow that has organically originated within the community. The intention is to create clearer processes and standards that support an open and responsive governance system.
Current Workflow
FIP0001 currently describes the FIP work flow as:
[ WIP ] -> [ DRAFT ] -> [ LAST CALL ] -> [ ACCEPTED ] -> [ FINAL ]
Though FIP0001 does define each of these steps, there has been signficant 'process collapse' around and between WIP and Draft statuses. This is primarily due to lack of specification around how an idea becomes a FIP and the de facto use of the FIP repo 'Issues' log as a community deliberation space.
The original intent of FIP0001 assumes is that a FIP author will take an idea and 'start' the FIP process by immediately pushing a draft. It was likely assumed that immediately creating a FIP draft was the best way to track changes over time.
However, the reality is that many FIP authors prefer to first share ideas and gather feedback in a formal way. The FIP 'Issues' log has filled this void by providing a space to log ideas, discussion, feedback, and early draft proposals in a way that is more accessible than Slack. Over time, the 'Issues' log has grown into a de facto part of the process.
Today, it hosts FIP ideas of varying levels of doneness, conversation topics, "back-burner" proposals that have been left untouched for over a year, and other community notices. Many FIP authors have begun to author entire FIPs in the Issues log because it is a more convenient place for making edits, and gathering and reviewing feedback. Deliberation is a critical part of the FIP process, and the 'Issues' log has emerged as one of the primary points of documentation for community deliberation of an issue.
As such, when community members strictly adhere to the process in FIP0001 and start by pushing a new idea directly to the repo, it appears as if they're "skipping" the process of community deliberation. This becomes both a documentation and governance legitimacy problem, and makes work difficult to track.
Lastly, because of the uncodified role that the 'Issues' log plays for hosting ideas, working on FIP drafts, and gathering community feedback, it is difficult to create a clear timeline for FIP adoption and visualize where each proposal is in the broader governance process.
Proposed Solution
To address these issues, I propose creating distinct spaces for 1) working on ideas, and 2) proposing FIPs.
In the ideas stage, community members use the newly -created FIP Discussion Forum to propose ideas, discuss topics, and ask questions.
This channel recreates the benefits of the 'Issues' log- the documentation of ideas in a forum, where edits can be made without needing reviewer approvals- while enhancing overall organization by dedicating the entire discussion space just to ideas, notices, and conversation topics. Forum moderators will thus be able to provide resources and steward good ideas through the FIP process, and will be able to clearly distinguish actual FIP drafts from other conversations.
Once an idea is ready to go from 'idea' to 'FIP', a FIP draft will be formally added to the FIP repo Issue log. This will allow community members to record comments, ideas, and other 'deliberative' ideas in a single thread, making edits to the draft over time. It will also be clear to the community which FIPs are more imminently in devlopment, as the only thing in the Issues forum should be FIPs that are actively working towards network acceptance. If the FIP has technical specs or code, these should be made available in unmerged branches and indicated in the FIP.
Finally, once the draft is complete and there are no outstanding community contributions or concerns which need to be addressed, the FIP author will submit a PR of the entire, completed FIP draft. This indicates that the FIP draft is complete as-is and is ready for 'Last Call'. The 'Last Call' draft will be stewarded to the broader community and merged once accepted.
The below graphic visualizes how different stages of FIP development would correspond to dedicated spaces in Github:
Concluding Notes
As a decentralized protocol, it is critical for network governance to be an open process. Openness is a function of accessibility, which these proposed changes seek to enhance.
There are additional structural benefits that this proposed process might provide, while requiring new clarification in certain areas. It is also true that there are FIPs already in-progress that would need to be transitioned into the new process, and broader community change management would need to be enacted to make this proposed process change successful. Please note that these items, as well as other trade-offs and challenges, were considered in the construction of this proposal. They aren't detailed here in order to keep the length of this proposal reasonable.
As always, additional questions, ideas, or feedback on this proposal are welcome.
Beta Was this translation helpful? Give feedback.
All reactions