llvm-www
llvm-www copied to clipboard
llvm
[LP-0004] Proposal for project governance
This PR introduces a proposal for project governance for the LLVM projects.
Thank you for working on this proposal, I think it is really good. I do feel like there is a lot of uncertainty about how some of the policies will play out especially with the voting and team composition, so we should not be afraid to amend the policy as needed after it has been implemented.
The one thing I would like to see in the proposal is some guidance around how often the Area Teams and the Council should meet. It seems like monthly meetings would be a good idea especially since the Area Teams are responsible for ongoing maintenance of the code owner lists.
Thanks for bringing this proposal! It looks like a good step in the right direction. I think some things are still unclear that need to be clarified:
- Who is responsible for facilitating the voting? The consensus votes and the votes for the area teams. We need to have this spelled out. It could be the current project council. In any case, this needs to be clarified so that it won't be delayed or confused when it's time to vote.
- As part of the "infrastructure team" currently, one pretty frustrating thing is that even if we work on these things, not all of us have access to the servers, github, discord, etc. We need to ensure that you have access to the necessary changes if you are elected to the infrastructure team. This must be coordinated with the foundation since some infrastructure is in their hands.
- We need a "community team" or something similar with moderator access to discord and discourse. The current moderators have not been elected, just assigned. This can also be a way to acknowledge people doing a lot of work on the community side but not as much in code.
- It would be good if the project council was also responsible for electing the release managers. To make that very clear, it would also help to give the release managers a mandate.
These are my initial thoughts. Except for clarifying the voting facilitators, I don't think the rest of my points are any blockers in any way, and adopting this proposal would be a net benefit for the community.
I have two high-level pieces of feedback:
First, while this outlines a lot of bureaucracy around how area teams are formed and fit into the larger structure, I find the proposal somewhat light on what the area teams actually do and what processes they use for that purpose. The proposal has some high level goals like "facilitate decision making", but little in the way of specifics. Does the area team only get involved in RFCs once they become contentious, or do they also have some role in the normal RFC process? E.g. does the area team have to explicitly say an RFC is approved, even if the discussion was non-contentious in the first place?
Second, I think there is an incoherence here between the required qualifications for the area teams, and their stated authority. The proposal says both that members of an area team "are not required or expected to be experts in the area the team is responsible for", but also "the area team may act as the final decision maker". I believe that either a) the area team should only be responsible for moderation and procedural matters, in which case membership can be arbitrary, or b) the area team has decision making powers, in which case it should be comprised of domain experts and have no limits on terms.
I think there is a pretty hard split in terms of overall process between these two options. With the processes outlined in this proposal, area teams should not have decision making authority on technical matters (only on procedural ones). An alternative process where they do would look much closer to how Rust teams work (where teams consist of domain experts only and new members are elected by the team itself, not a global election).
I should add that I think more structured governance is long overdue, and I'm in favor of having some people take on more proactive roles in making things work smoothly. I have some quibbles with how this proposal is described, but it seems like a reasonable enough first cut. I could wish for more evidence of checking in with software-engineering academic research, beyond looking at one book, but mostly that's just my own prejudices talking.
At least for the first round, I think The Foundation would have to run the nominating and election processes.
Random Q: is this really a matter for the decision making process? It is suposed to be used when there is a dispute of some sort - have you considered just starting this as an RFC to shake out the contentious issues? I'm sure there will be some ;-)
Random Q: is this really a matter for the decision making process? It is suposed to be used when there is a dispute of some sort - have you considered just starting this as an RFC to shake out the contentious issues? I'm sure there will be some ;-)
I think this is a matter for the decision-making process in general and not just dispute resolution.
@tru wrote:
- Who is responsible for facilitating the voting? The consensus votes and the votes for the area teams.
The intent here is that we shouldn't have votes for consensus. There are lots of problems with using voting to drive consensus, the intent here is to empower people to make a final decision, not describe a way to poll the community.
In my mind the LLVM Foundation can help facilitate elections, and should act as a neutral body doing so. I'll clarify that in an update.
@tru wrote:
- As part of the "infrastructure team" currently, one pretty frustrating thingis that even if we work on these things, not all of us have access to the servers, github, discord, etc. We need to ensure that you have access to the necessary changes if you are elected to the infrastructure team. This must be coordinated with the foundation since some infrastructure is in their hands.
This is somewhat of a separate issue outside this proposal. Right now administrator access to Foundation-controlled assets is pretty tightly held. The board has a line item on the agenda for our next meeting to discuss this problem.
@tru wrote:
- We need a "community team" or something similar with moderator access to discord and discourse. The current moderators have not been elected, just assigned. This can also be a way to acknowledge people doing a lot of work on the community side but not as much in code.
I think this probably touches on an area where my proposal is too vague. The elected teams in this proposal are not elected to do the work maintaining an area (although they will likely be maintainers). The purpose of the teams initially is to provide a scalable structure for decision making and delegate responsibility for maintenance of the code owners. I see this as a first step in an evolving process.
@tru wrote:
- It would be good if the project council was also responsible for electing the release managers. To make that very clear, it would also help to give the release managers a mandate.
This isn't something I had considered. I mostly tried to stay clear of redefining parts of the existing project structure (code owners, release managers, infrastructure maintainers, moderators, etc). I can see how there is probably some value here in folding the release managers in somehow to empower them and give them a clear mandate. Maybe you (@tru), @tstellar, and I can chat sometime to explore that idea.
@nikic wrote:
The proposal has some high level goals like "facilitate decision making", but little in the way of specifics. Does the area team only get involved in RFCs once they become contentious, or do they also have some role in the normal RFC process? E.g. does the area team have to explicitly say an RFC is approved, even if the discussion was non-contentious in the first place?
There is a significant amount of ambiguity here, and some of that is intentional, some of it is not. Our existing Developer Policy gives Code Owners no real authority, but as a community we implicitly grant them authority to do a lot. My goal for this policy was to grant the Area Teams a narrow slice of authority and see how the role grows.
The responsibility to "facilitate decision making" is somewhat analogous to our Code Owners having the sole responsibility to "ensure that a commit to their area of the code is appropriately reviewed". The Area teams should avoid making decisions and instead seek to help the relevant parties in the community come to agreement.
@nikic wrote:
Second, I think there is an incoherence here between the required qualifications for the area teams, and their stated authority. The proposal says both that members of an area team "are not required or expected to be experts in the area the team is responsible for", but also "the area team may act as the final decision maker". I believe that either a) the area team should only be responsible for moderation and procedural matters, in which case membership can be arbitrary, or b) the area team has decision making powers, in which case it should be comprised of domain experts and have no limits on terms.
I have two thoughts here:
- I can't realistically imagine many people being elected to an area team with zero expertise. Our community is comprised almost exclusively of extremely intelligent technical individuals. I want the language to calibrate the bar low because in practice underrepresented minorities tend to self-select out of leadership roles if they don't feel they meet the requirements. This language is intended to head that off.
- I probably need to clarify what it means to "act as the final decision maker". I don't think that this means pulling a decision out of thin air. This is really about resolving a disagreement with a lasting decision. The area teams should strive to act neutrally, and their decision should be based on weighing the arguments of both sides and prioritizing the long-term health of their area and community. I don't think you need to be a technical expert to do that. IMO the skills required to be good in that role aren't strictly coding/engineering skills they're soft skills.
@nikic wrote:
An alternative process where they do would look much closer to how Rust teams work (where teams consist of domain experts only and new members are elected by the team itself, not a global election).
I looked a lot at Rust. I think Rust's approach has some serious problems. The whole mess with the Rust moderation team a few years ago was deeply rooted in the "Core team" being self-appointed and not accountable to the community. The new Leadership Council they adopted shifts the problem down, but doesn't fully resolve it. The Leadership Council is elected by the teams, so they have accountability, but the teams are still self-appointed and accountable to nobody but themselves. I strived here to make each layer accountable to someone and ultimately give the community voice.
@pogo59 wrote:
I could wish for more evidence of checking in with software-engineering academic research, beyond looking at one book, but mostly that's just my own prejudices talking.
If you have any resources you would recommend I'd love to read them. I dove into this over the summer and have been leaping at everything I can get my hands on, but I don't have a lot of exposure to academic research in this area.
@pogo59 wrote:
At least for the first round, I think The Foundation would have to run the nominating and election processes.
Yea, I think the Foundaiton should take an active role in facilitating the elections. The Foundation's legal entity will be required in order to collect the voter database and comply with data privacy laws so I think that's the right approach.
@lattner wrote:
Random Q: is this really a matter for the decision making process? It is suposed to be used when there is a dispute of some sort - have you considered just starting this as an RFC to shake out the contentious issues? I'm sure there will be some ;-)
I went this direction for a couple reasons. First, I felt that we probably needed the finality that the Decision Making process provides because we're almost certainly going to settle on some details that not everyone will agree with. I also think that part of this PR will ultimately need to include a revision to the Decision Making Process document to codify responsibilities of the new teams. That's just one more reason it will need to end up here eventually.
I also felt that responding to feedback and iterating on this document in a code review rather than a discussion thread was going to be much more managable. As it is, catching up on all the feedback as I've been digging out from the Dev Meeting has been hard, but GitHub is much easier to manage than Discourse for this.
What are the next steps for this proposal? It seems like there is consensus on the general idea of project governance, but maybe not on all the specifics. Should we start moving this proposal through the existing decision making process?
@tstellar I have some updates to the doc locally that I will try to get posted either today or Monday. Then hopefully interested parties can review and we’ll see where that lands us.
Hey. I was excited to see this because I agree that there are some significant problems in our current governance. With that said, though, I had a couple of thoughts as I read this over.
The first is that I think it's really important for proposals like this to be very clear about problems and goals. The Motivation section assumes from the first sentence that the reader already knows about the "systemic problems with making decisions". I agree that there are problems in LLVM governance, and I think most people in the community do! But I don't know if the problems I see are exactly the same as the problems you see, which makes it hard to know how to respond to your proposal. If I think some part of this proposal might be ineffective at addressing a particular problem, should I be exploring better mechanisms, or should I be trying to convince you that that problem is more important to address? Conversely, if I think some process in the proposal seems overly baroque, should I suggest a more lightweight approach, or do I first need to try to understand why you think it's important to have extra process there?
If I were writing this, these are the problems I'd be talking about:
-
Some patches aren't getting timely review because there isn't always effective code ownership of the codebase.
-
Patch authors sometimes feel like they're getting a runaround on their patches from reviewers and that reviewers are adding significant and unnecessary complexity. There isn't a clear policy about what kinds of changes are okay to ask for, and there isn't a clear dispute process for patch authors to follow when they think the requested changes are unreasonable.
-
The RFC process mostly entails hoping that a consensus rapidly emerges in favor of your proposal. If an RFC isn't getting much discussion, does that mean people are generally okay with it, or does it mean that nobody's seen it, or does it mean that nobody wants to deal with it and everybody is hoping that it just goes away? We don't have a process for ensuring that there's eventually a clear positive or negative signal on any particular RFC.
And then we can talk about which of those are actually being addressed by this proposal. I don't know if we agree that those are the biggest structural problems to be addressed here, though. I do agree with your suggestion that RFCs and code review too frequently get over-heated, and I think that's a serious problem. However, I think that's largely downstream of the lack of a clear dispute resolution policy, because the ideal of "just reach consensus" decays to "try to argue it out until someone's convinced" real quick. If it were closer to "make your case to a larger audience", I think it'd feel a lot less like a personal conflict, and there'd be less heat, and it'd be easier to address any remaining heat as a CoC issue (and usually a light touch is all that's necessary). Anyway, that's certainly been my experience in the Swift community, but of course people can reasonably disagree about it.
My second thought is that the Area Teams concept seems really strange. I don't know who's going to want to serve on all these little committees that, frankly, don't seem to do very much on their own. They explicitly don't have any technical authority, or even expertise, and seem to be primarily be conflict mediators. Are we expecting this to be a way of showing leadership and gaining credibility in the community? Why is this role even area-specific? I'm not sure I as a contributor would know who these people are, especially given the requirement that they rotate on a fairly quick basis.
It seems to me like a better approach would be to build on and broaden the existing concept of code ownership. In my experience, just having people talk on a regular schedule with a well-organized agenda is the best way to both (1) build consensus and (2) ensure eventual progress. So I'd say that the technical leaders in any particular domain should just pick a chair among themselves and set an agenda every month or so to make sure that all the RFCs, contentious reviews, and so on actually get decided on. Those groups should at least be the existing code owners, but probably a little broader than that. They can invite whoever they'd like to join, but the expectation should be that they regularly invite new people. To ensure accountability on that point, they should have to report their membership up to the project, and the project should call them out if the membership seems too static or if it looks like somebody's being deliberately excluded.
My last thought is that I don't really know how this proposal gets approved and comes into effect. We don't have a decision-making process for this! This is basically a whole new "constitution" for the project, and if anything has ever needed broader community-wide legitimacy than we can reasonably attain by RFC or by Foundation fiat, this is surely it.
I consider the latter two points are sort of secondary, at least for now. What I'd really like to see first is that change to the Motivation section to be much more explicit about laying out the problems you see in LLVM, identifying your goals for how these governance changes will address those problems, and (presumably) identifying any non-goals, e.g. problems you think should be addressed in other ways. If you can do that, I think it'll be a lot easier to have a constructive conversation here.
Let me just finish by emphasizing that I'm really excited to see this proposal and that I look forward to having better decision-making processes in LLVM.
Dear Community,
Having thoroughly reviewed the LLVM governance proposal, it's disconcerting to note an abundance of buzzwords, a clear deficit of substantive content, and a full-scale introduction of corporate bureaucracy. While the intention to address community challenges is evident, the proposal appears to prioritize style over substance, risking unnecessary complexity. Notably, it's crucial to highlight that the proposed changes do not address the fundamental issue of code ownership, maintaining the existing role's limitations without fostering meaningful transformation. It not necessarily mean that it's bad, it's just address a different kind of issues that are not visible to me. Sections like "Core Values" are so obvious, that they fell more like a redundant duplicate of Code of Conduct. Area Teams does not solve everything, they solve close to nothing, this sounds like more like a Team Product Owners trying to resolve a dispute between developers, where the code architects should do that. But many projects do not have a vision, do not have a roadmap or architecture plans, therefore misunderstandings.
I propose a reevaluation that prioritizes an agile solution suited to our dynamic community, avoiding unnecessary overhead. It's crucial to address pressing issues like improving code review throughput and resolving code ownership concerns, as highlighted by fellow community members.
Solution that I would like to see would utilize Github pull request.
RFC changes:
- User create pull request with [RFC] in title, puts some .md file in folder location of "area" with description of change.
- Github Actions checks main contributors to that folder in last 12 months, and add them as reviewers
- Every contributor vote with "Accept/Request changes" or with emotes (thumbs up/down)
- RFC is accepted/rejected once 50% of contributes vote
- RFC is accepted/rejected once 1 month pass [selectable from 1 month to 3 month] (time limit is crucial) based on current vote results
Code owner selection:
- Volunteer to code owner create pull request with CODE_OWNERS.TXT file changed
- Same voting like for RFC + other interested people
Code review:
- "Stuck" review gets additional label (STUCK) added by github actions after 1 month of inactivity, maybe number of them could be listed on main repository page.
- Pull requests stuck in "requires changes" are auto abandoned after 6 months of inactivity
- Stuck code review (but not in requires change state, and not with open comments) are auto approved after 3 months of inactivity
- Contributor need to know that if they spend 20h to develop something, they at least will receive feedback
- Contributor may be the only maintainer, and it can be hard to find code reviewer
- Code owner reviews would be auto approved after 1 (or 2) month of inactivity, code owner have problems with finding reviewers & and getting approve for their own reviews
- In short using "fear": if you don't want something to be merged, then better review it.
- Or some other process that would solve this, like thread on disclose, or something
This is my perspective: the primary concept involves incorporating time constraints, keeping it simple, and automating where possible. However, the ultimate decision is yours. Perhaps there are aspects I'm not considering, but I sense that the issue might lie at a more fundamental level than what this proposal aims to address.
@PiotrZSL
Dear Community,
[...]
RFC changes:
- User create pull request with [RFC] in title, puts some .md file in folder location of "area" with description of change.
- Github Actions checks main contributors to that folder in last 12 months, and add them as reviewers
- Every contributor vote with "Accept/Request changes" or with emotes (thumbs up/down)
- RFC is accepted/rejected once 50% of contributes vote
Thanks for sharing your thoughts. I don't want to dismiss anything you've said here and I do think there are some interesting ideas, however I must say that I personally don't think a 50%+1 policy for making technical decisions is a good idea. When it comes to making technical decisions, I believe we need a process where consensus is determined in a reasonable fashion while taking into account folks' opinions, but while also being able to weigh in different factors, which something systematic like 50%+1 of votes doesn't allow for. Sometimes, the right technical decision is not what the numerical majority wants, yet it might still be what's best for the project, users and ecosystem.
Also, just as a matter of process, it might make sense for you to write down your RFC into a PR similar to @llvm-beanz's if you want to pursue it. This would provide a cleaner way for folks to provide feedback on your RFC without hijacking this thread.
There's still hasn't been much movement here, what can we do to move forward?
Would it make sense to run a trial of this proposal with just a single area team so we can get the infrastructure for voting in place and to see how things work out. I know we could really benefit from having a "Project Infrastructure" team. We have several outstanding issues that we are having trouble making decisions on and I think having an area team would really help.
Hey @tstellar, sorry I haven't reported back here. I'm working on a revision to the document based on feedback. I'm not sure if I'll get it done by the end of this week or not.
I like your idea of a trial with one team. I think we have a bunch of logistical issues to work through to even get to that point, but it might be a good starting goal.
In addition to incorporating the feedback from comments that I haven't yet gotten to, one of the things that is high on my to-do list here is drafting more concrete details around how to handle voter registration and the required privacy policy that we'll need in place.
I'm aiming to get drafts of most of that together this month.
I really like the proposal for improving project governance, but I also share the concerns raised about area teams in the other replies. In particular:
https://github.com/llvm/llvm-www/pull/54#issuecomment-1759220410 (nikic)
... I believe that either a) the area team should only be responsible for moderation and procedural matters, in which case membership can be arbitrary, or b) the area team has decision making powers, in which case it should be comprised of domain experts and have no limits on terms. I think there is a pretty hard split in terms of overall process between these two options. With the processes outlined in this proposal, area teams should not have decision making authority on technical matters (only on procedural ones).
https://github.com/llvm/llvm-www/pull/54#issuecomment-1815305288 (rjmccall)
My second thought is that the Area Teams concept seems really strange. I don't know who's going to want to serve on all these little committees that, frankly, don't seem to do very much on their own. They explicitly don't have any technical authority, or even expertise, and seem to be primarily be conflict mediators. Are we expecting this to be a way of showing leadership and gaining credibility in the community? Why is this role even area-specific? I'm not sure I as a contributor would know who these people are, especially given the requirement that they rotate on a fairly quick basis.
@rjmccall's suggestion to "build on and broaden the existing concept of code ownership" is an interesting alternative. Perhaps we should explore this option further before establishing a new group.
Once we have a good definition of area teams and decide to move forward, I agree with the idea of starting with a single, well-defined area like some part of llvm/ or clang/. This would allow us to test and refine the approach before scaling it up. Some subprojects might have relatively smaller communities and fewer RFC proposals that would lead to disagreements, making a dedicated area team feel like an unnecessary burden.
My second thought is that the Area Teams concept seems really strange. It seems to me like a better approach would be to build on and broaden the existing concept of code ownership.
+1
I have some perspective on this in terms of Clang code ownership. The feedback I've gotten from Clang code owners can be summarized as "I am drowning with community responsibilities already, please do not give me more responsibilities." In fact, I would not be surprised if making area team membership a mandatory aspect of code ownership led to (a small number of) code owners stepping back despite otherwise being active in their role.
I think it's perfectly reasonable to encourage code owners to join an area team, but I'd be wary of tying the two responsibilities together directly.
Also, another thing I think is important to consider is that code ownership is largely about managing technology while area team membership is largely about managing people via a process. Code ownership still touches on people things and area team membership still touches on technical things, but I think the skill set needed to be successful in the roles might be slightly different.
My second thought is that the Area Teams concept seems really strange. It seems to me like a better approach would be to build on and broaden the existing concept of code ownership.
+1
I have some perspective on this in terms of Clang code ownership. The feedback I've gotten from Clang code owners can be summarized as "I am drowning with community responsibilities already, please do not give me more responsibilities." In fact, I would not be surprised if making area team membership a mandatory aspect of code ownership led to (a small number of) code owners stepping back despite otherwise being active in their role.
I think it's perfectly reasonable to encourage code owners to join an area team, but I'd be wary of tying the two responsibilities together directly.
Also, another thing I think is important to consider is that code ownership is largely about managing technology while area team membership is largely about managing people via a process. Code ownership still touches on people things and area team membership still touches on technical things, but I think the skill set needed to be successful in the roles might be slightly different.
+1 - I am also struggling with the commingling of technical and administrative/management responsibility and reconciling it with the fact that many of the most productive contributors will see this as, at best, a necessary service vs something sought after. I'm struggling with how to phrase this without coming off as rude, but the thing I want for the project is for the most level headed pragmatists who don't necessarily want the job to be the ones that make it to these key positions that have any implied authority. In effect, I want the people who are conscientious, mostly keeping their heads down, and have a broadly developed view of what is going on to be empowered. I'd also like for them to not be drowned in administrative duties.
I don't know how to reconcile those desires, but what I fear is that we create something that starts to feel more like a home owners association vs an act of service.
Perhaps instead of codifying very detailed responsibilities, term limits, voting requirements and rules up front, we put a one year time limit on the process itself and require that we draft a v2 based on learnings from the teams that were the most effective over that term. Something like that might help us grow into things while also giving all of us a right of review, so we know things can be fixed without a lot of drama. i.e. when faced with a big change and a lot of people, one can either nail everything down in a process of consensus or the cost of getting it slightly wrong can be reduced by explicitly making it a thing that we agree to rev and improve.
Just my 2 cents.
(sorry for delayed feedback - I've been mulling this since it was posted and trying to figure out how to verbalize what isn't sitting right with me. thanks to the people who started hitting approve to get me to actually write down my thoughts)
Perhaps instead of codifying very detailed responsibilities, term limits, voting requirements and rules up front, we put a one year time limit on the process itself and require that we draft a v2 based on learnings from the teams that were the most effective over that term. Something like that might help us grow into things while also giving all of us a right of review, so we know things can be fixed without a lot of drama
+1. This is basically the same as some of my comments up-thread: Start much simpler, fail, iterate.
I'd start with understanding why we need such a council. Is it because code owners are not doing that job? Not supposed to do that job? Not easily removable? Can/should we fix the definition of code owners? Maybe just add more roles (admin, conflict resolution, community) and follow the current process we have for code owners?
There are many easier ways to be inclusive and to allow non-technical people to contribute to the core of our community without creating hierarchies and power division, voting schemes and fixed terms.
I always go back to @AaronBallman's reorg of Clang code ownership. That was a much more efficient process because it didn't change a lot, but it achieved a lot. Perhaps we can start from there, enhance the roles (not just "code" owner) and iterate through the sub-projects.
If some emergent feature becomes obvious, we encode it. Like we've always done in LLVM, our process is to document policy from existing behaviour, not to try and force behaviour through new policy.
FWIW, I am not ok with this current proposal for project governance. I won't stand against if there is consensus, but I don't think we're going in the right direction.
More importantly, I don't think we'll be more inclusive. On the contrary, I believe we'll enforce conscious bias through policy in an attempt to remove unconscious bias through actions.
I'm not going to go so far as to say I don't support this being tried in some fashion. But I do believe this approach is likely setting us up so that common sense does not have the upper hand over time.
I do agree with the sentiment that something needs to change. What we are doing isn't working at the present scale. But we are not at the bottom: do this wrong and it can get worse.
I'm willing to try anything for a year. In fact when it comes to change, I prefer to be able to just put the objection out of my mind and give it a try -- taking a break from trying to logic my way to something better and giving myself time to adapt. From that perspective, I'd rather see something time limited. We can always pull the plug if it is a disaster at any time, but planning for the more likely scenario that it helps some things and regresses others, I work better knowing there is a future date we can address that stuff vs trying to incremental it in real time. Both let's me park a mental thread and gives time for my gray matter to assume a new form before spending mental energy on a prior state.
I'm not going to go so far as to say I don't support this being tried in some fashion. But I do believe this approach is likely setting us up so that common sense does not have the upper hand over time.
I do agree with the sentiment that something needs to change. What we are doing isn't working at the present scale. But we are not at the bottom: do this wrong and it can get worse.
I've been pointed back to this review recently, and I want to make clear my words probably sound harsher than I wanted them to be. What I was trying to say is exactly what @stellaraccident said here. That's why I "thumbed up", but that doesn't help other reading my own reply.
So let me be clear:
- I am not against this proposal: I think it's long due and we really need this. I'd love for us to have something to iterate on.
- I am unhappy that we're encoding too many hypotheticals, which can serve as undue metrics that people can use (unintentionally) as arguments in upstream discussions ("the doc says so"). I'd rather use common sense, but sense is rarely common.
- I would very much prefer a leaner document that increases the number of cases over time, rather than a document we need to remove stuff because they have been weaponized. Both cause grief, but adding actual facts is easier than removing badly worded hypotheticals.
- I would strongly encourage us to have a paragraph with the following sentiment: "This document is a reflection of what we want the community to be. It may be wrongly worded, it is biased by the current writers, it will definitely get 'dated' as our community evolves. When any of those problems are detected, the first reaction must be to re-evaluate the document, not to use it as misguided direction because someone once wrote it."
- A follow up paragraph could be due: "However, we truly believe in what we write, so changing the document must be a new consensus forming process, and not cheaply done. More importantly, this is not just a description of the 'status quo' that we're trying to maintain, it's a proposal of the community that we want to be, and in that, it has powerful consequences and should not be treated lightly."
I'm willing to try anything for a year. In fact when it comes to change, I prefer to be able to just put the objection out of my mind and give it a try -- taking a break from trying to logic my way to something better and giving myself time to adapt.
+1 to this. Let's get something done and try it out, and if it doesn't work, we adapt. Nothing we haven't done before as a community.