docs(policy)_: Introduction of policy zero #6165
Conversation
Jenkins BuildsClick to see older builds (105)
|
Samyoul
force-pushed
the
policy/policy-zero
branch
2 times, most recently
from
aaadf85 to
a804bb4
Compare
|
@igor-sirotin Do you know why my conventional commits validation is failing? https://github.com/status-im/status-go/actions/runs/12259024416/job/34200188125?pr=6165 All my PR commits are prefixed with |
|
TODO. Add the README file |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## develop #6165 +/- ##
===========================================
- Coverage 61.21% 61.20% -0.02%
===========================================
Files 833 833
Lines 109925 109925
===========================================
- Hits 67291 67276 -15
- Misses 34761 34770 +9
- Partials 7873 7879 +6
Flags with carried forward coverage won't be shown. Click here to find out more. |
@Samyoul yes, because PR title must follow the same rules as commit messages. |
igor-sirotin
requested review from
friofry,
dlipicar,
igor-sirotin,
osmaczko and
a team
There was a problem hiding this comment.
Although I left a few comments, I think this Policy Zero PR is a welcome addition 💯
I usually prefer more soft guidelines and building trust among core contributors instead of hard policies. Some policies are obviously good (e.g. PR descriptions).
Or in other words, I think a more healthy open-source project is one where policies are minimized and guidelines thrive because the best software engineers I worked with are the ones who use guidelines as tools. But maybe status-go and Status will greatly benefit from policies, so let's see 👀
_docs/policies/README.md
Outdated
| # Foundational Principles for Policies | ||
|
|
||
| **Purpose**: Policies establishes the fundamental rules that govern the creation, amendment, and enforcement of all actions within the status-go project. These policies reflect our core | ||
| values of inclusivity, transparency, and consensus-driven decision-making while defining enforceable rules that guide status-go contributions. Policies are not merely guidelines but are to be |
There was a problem hiding this comment.
It's unclear to me how the line will be drawn between guidelines vs policies. A policy is being stated as if it's the law, which in some cases could well be the way to go, but there's room for some people to abuse this policy system. At the same time, I much prefer this over a dictatorship model as many open-source projects follow.
There was a problem hiding this comment.
Thank you for saying this. I 100% do not want this to be abused, I hope that have a very high quorum and a very high level of required consensus that it will make abuse more difficult. As we discussed offline I will continue to put serious thought into this.
There was a problem hiding this comment.
-
TODO: Improve the concept of policy versus guidelines. -
TODO: Address the concept of "enforceability".
|
|
||
| # Review and Approval Process | ||
|
|
||
| The core function of the review and approval process for policy PRs is to reach consensus on any issue and to reflect the range of perspectives within the `status-go` community. Policy submissions must aim to achieve broad community support and give key stakeholders a chance to gain context of the policy requirements. |
There was a problem hiding this comment.
I still think that this part if redundant. It basically summarises what's described in the README: consensus, transparency and inclusivity.
But let's see what others say.
_docs/policies/README.md
Outdated
| - **Final agreement**: Policies should be approved by a clear consensus, meaning that while not everyone may agree 100%, all should feel their voices were heard and respected, and the final decision | ||
| reflects the community’s general will. | ||
|
|
||
| ## 4. Enforceability and Respect for Policies |
There was a problem hiding this comment.
This part is probably the most important.
Although that sequentially I'd also put it after Inclusivity, Transparency and Consensus, I feel that it might be better to make it first. Otherwise most readers will not reach this most important part.
There was a problem hiding this comment.
-
TODO: Address the concept of "enforceability".
There was a problem hiding this comment.
@igor-sirotin, @ilmotta, @micieslak and @alaibe
I've thought a lot about input from everyone on this particular subject of enforceability and I feel that I've failed in communicating well enough what our approach is. Given that you all have expressed your opinions on the concept of enforcement and enforceability would you mind giving me your thoughts on my newly phrased section for the subject.
Upholding Policies Through Consensus
Collective Agreement:
The enforceability of policies stems not from the authority of any single individual or group but from the collective agreement and shared commitment of all status-go contributors. Policies are not imposed unilaterally but are the result of transparent discussions and explicit recorded approval from key stakeholders. This includes team leads, members of the @status-im/status-go-guild GitHub team, and other relevant contributors.
Shared Responsibility:
Respecting and adhering to policies is a shared responsibility that reflects the values and goals of status-go contributors. Approved policies are not merely recommendations but agreed-upon standards, created through mutual understanding and collaboration, that guide how we work together and contribute to the project.
Mutual Enforcement through Alignment:
The power of enforcement does not rest with any one authority; it arises from the collective commitment of all contributors to uphold policies that have been collaboratively crafted and agreed upon. This ensures that policies are respected not out of obligation but because they represent the shared vision and trust of the contributors.
Fostering Alignment:
Policies are designed to ensure consistency, fairness, and alignment across the teams, creating a framework that supports effective collaboration and decision-making. By honouring the principles of inclusivity and consensus, we strengthen trust and accountability within all contributors.
By grounding our policies in transparency, mutual respect, and collective ownership, the status-go project ensures they are both enforceable and reflective of the shared goals of all contributors.
cc: @status-im/status-go-guild
igor-sirotin
changed the title
_docs/policies/README.md
Outdated
|
|
||
| - **Key stakeholder approval**: The guild does not have unilateral enforcement power. Instead, policies require explicit recorded approval from all key stakeholders before becoming enforceable. This | ||
| includes team leads, the status-go Guild, and other relevant parties. | ||
| - **Respect and adherence**: Policies are not optional guidelines. Once approved, they are enforceable rules that all contributors to the status-go project are expected to respect. This ensures |
There was a problem hiding this comment.
It's a bit unclear to me how the enforceability may work on a daily basis and how we can be sure that the policies are fully respected. Are reviewers the ones who are responsible for verification of given part of code regarding policies? Different people have different levels of understanding and can enforce them to different degrees. In practice, old habits also do well because they allow to move forward easily, even if it is a short-sighted action. Adjusting to new arrangements often means spending extra time to understand them and leaving the comfort zone, both for pr author and reviewers. In practice, this results in incomplete implementation of the arrangements. The question is whether we have any specific arrangements on how to counteract this
There was a problem hiding this comment.
TLDR; Policies should not define HOW they're enforced, but define WHAT we agree to enforce.
This is just an instrument to agree on the rules of the game.
And we don't expect to have many policies.
It's a bit unclear to me how the enforceability may work on a daily basis
In my opinion, the real question should be: How can we ensure every core contributor is fully autonomous and able to contribute safely? Instead of asking, How can we enforce everything?
It depends on the certain policy. But in most cases it should be automated.
For example, "pull requests must have > 50% diff code coverage".
Obviously, it can't be checked by reviewers and should be automated (which we did).
Another example, "breaking changes policy", is not easy to automate, so indeed it would be mostly one developers and reviewers shoulders.
There was a problem hiding this comment.
Thank you @micieslak, I have personally struggled with the concept of enforceability and where we draw the line between guidelines and rules. I don't like rules, and I don't like arbitrary rules.
The points you make are all reasonable and thoughtful, and I agree with everything you write, these are legitimate everyday scenarios. I believe that some cultural changes may be necessary from all status-go contributors and this will in some cases cause some slowing down of development speed. This is not a bad thing, in many cases it should reduce the overall development and QA time spent on features.
My opinion is that policies should be a social contract that status-go contributors agree to, this is why I have included a lot of detail about the importance of consensus and inclusivity. Policies should be introduced for things that can not be automated but are still essential for the long term health of the repo. The examples Igor make are good ones to highlight, as they show a distinction between what is automatable and what is not, yet both are needed for the long term health of the repo.
old habits also do well because they allow to move forward easily, even if it is a short-sighted action.
This particularly is an incredibly important point Michał, and it is in fact a major motivator for introducing a policy process that requires a high level of consensus. By engaging all contributors and leads my personal hope is that short-sighted behaviour will be seen as somewhat selfish and generally detrimental to the work of our fellow contributors, even across teams and specialities.
By requiring a very high level of consensus for any policy we can build mutually approved guidelines that will ensure that contributors from many teams and backgrounds have clear expectations and an even playing field.
Please see #6165 (comment)
|
I agree with the point above—policies are only valuable if they are enforced. I’ve seen many policies that were never enforced and ended up in limbo. Wouldn’t it be better to focus on building shared knowledge rather than trying to police everything? In my opinion, the real question should be: How can we ensure every core contributor is fully autonomous and able to contribute safely? Instead of asking, How can we enforce everything? Lately, there’s been a trend of issuing messages “by decree of the guild” followed now by a new policies system. However, I don’t recall being invited to demos showcasing what can already be done in, for example, status-go, or how the guild has improved things over time (and u guys did, no doubt). Instead, I often see decrees and policies. To be clear, I do believe that adding policies is sometimes necessary and valuable—this is why I’m approving the PR. However, I’d love to see a shift towards a different approach: focusing on sharing knowledge rather than merely enforcing it |
💯
@alaibe Or I think I'm missing your point about "sharing knowledge"?
I am sorry if we made you feel this way. We never liked this and only allowed ourselves to use This policies system is exactly to prevent such one-sided notification system. |
|
The backbone of the Status product, aka status-go, is a place without ownership (there's no dedicated team; the status-go guild is just a collection of CCs from different teams who try to improve things on a best-effort basis). status-go is developed by every team in Status, and that's fine, as the work is mainly driven by business priorities. The lack of ownership has an obvious drawback, which is the health of the codebase. People jump in, implement features, and jump out. The frequency of such actions varies greatly between contributors and usually goes hand in hand with the quality of the changes. I believe that, in such an environment, guidelines are not enough. Note that policies can and will go hand in hand with guidelines. In the past, we've struggled a lot with regressions, breaking changes, and development speed—all caused by the workflow we've had until now. The initiative with policies is to agree on things that are a clear MUST for status-go to improve. The process is designed to establish consensus among CCs before introducing any enforced policy. This is exactly to avoid decisions made in isolation and announcements like "By decree of the guild." The number of approvals and potential discussions makes it difficult to add or change policies, which, we believe, will result in a limited number of well-thought-out, high-quality, and unambiguous policies. Policies will be enforced by CI checks, where possible. |
There was a problem hiding this comment.
Thanks for the PR.
I think we missed an important aspect, which is how to handle exceptions to the policies. I am pretty sure there will be some, and we need to apply common sense in this case. If there are many approved exceptions, it means the policy is wrong and needs to be re-formulated.
I propose to add:
Policy exceptions
- Exception to the policy MUST be documented with a clear justification in textual form.
- Exception to the policy MUST be approved by at least one team lead (of Status Desktop and Mobile).
- Exception to the policy MUST be approved by at least one member of the status-go Guild.
- Policies MAY define additional rules for exceptions, provided these baseline requirements are also met.
|
|
||
| Policy Zero establishes the foundational guidelines for creating, reviewing, and maintaining policies in the `status-go` GitHub repository. This policy aims to create a collaborative, inclusive, and transparent process for defining repository policies, specifically regarding how developers engage with and contribute to the repository. | ||
|
|
||
| # Submitting a Policy Proposal |
There was a problem hiding this comment.
I believe it would be helpful to include the justification for the given policy as well.
- A policy MUST include a brief justification, addressing the question: "Why has this policy been introduced?"
There was a problem hiding this comment.
That is an excellent point and I will add that now
There was a problem hiding this comment.
I actually added this to my latest pending commit.
I recall the common understanding we agreed upon: |
|
We can also specify codeowners for this directory, according to the rules in the policy: /_docs/policies @status-im/status-go-guild @iurimatias @alaibe @shivekkhurana @ilmotta |
|
Also, do you think we clear everything else in cc @status-im/status-go-guild |
|
@shivekkhurana I think we don't need this, as there should not be many policies. There should be not more than 5, worst case 10. So I wouldn't bother with a template in this case. |
|
@alaibe Your feedback here is very valuable, thank you for sharing it. I am very grateful that your thoughts were not made any later, as they all need to be addressed now. The points you raise are the exact reason why a lot of time was spent trying to build into this policy as much language on requiring a high level of consensus and inclusivity. The
This point is really important to me, and for what it is worth this is an internally joke about the impotence of the Guild, though when reflected through your perspective it communicates as a thoughtless mandate. I am sorry, I don't want anyone to feel excluded, let alone be excluded. We will not use language like "by decree ..." any more. Thank you Anthony for your input here.
I wholeheartedly agree with this sentiment. Policies should not exist in isolation or feel like rules imposed from above; they should be tools that empower everyone to contribute collaboratively and effectively. That’s why we’ve tried to weave into this process not only mechanisms for consensus but also a foundation of shared understanding and collaboration. To address your specific concerns more concretely, I propose we make a deliberate effort to prioritise transparency and knowledge-sharing as part of the policy process moving forward. For example, we could organise regular demos or discussions to showcase how existing processes or checks like those the Guild have already introduced to I also really appreciate your point about autonomy. Policies shouldn’t be about policing; they should be a means of ensuring that all contributors have the context, resources, and freedom they need to act independently while maintaining alignment with shared goals. If this aspect isn’t coming through strongly enough in our current approach, then it’s clear we need to adjust. Thank you again for your thoughtful feedback, Anthony. It’s through conversations like this that we can refine our approach and build a system that serves everyone better. Please don’t hesitate to share any additional thoughts or suggestions, we really need them. |
|
@osmaczko what do you think of the following: Also @friofry I've tried to incorporate your point: Basically making exceptions is ok, but documentation and EXPLICIT approvals are required. Policy OverridesOn rare occasions, circumstances may necessitate that an established policy is circumvented. This is considered an Override and MUST follow the process outlined below to ensure transparency and collective agreement:
|
|
Hey @shivekkhurana , Thanks for the review and your approval.
I know that this policy is quite formal, but if we have more than 10 policies total by this time next year that will be too much. I think for the moment we shouldn't attempt to formalise how policies are structured. That may become an evident issue we must address in time, but for the moment we should attempt to agree to just the basics. There is already some queries on our intentions and so for now perhaps we can set the foundation we currently have and iterate.
Yes I think that is basically what should happen. A record of the policy submission will exist as the PR and the discussion will be public for all to see. I would be very happy to hear any other step you think we should consider. |
Additionally I've inserted line breaks at 60 - 75 chars per line.
We want a fresh start lets start with zero and together work up from there
Samyoul
force-pushed
the
policy/policy-zero
branch
from
b36055a to
fec5c77
Compare
There was a problem hiding this comment.
I wish we didn't have to introduce this policy.
And I wish there was a simpler way.
However, in the circumstances of 5 teams working on single owned-by-nobody codebase, there's no other way.
Thank you @Samyoul for making this!
'4. Enforceability and Respect for Policies' with 'Upholding Policies Through Consensus'
Samyoul
force-pushed
the
policy/policy-zero
branch
from
ec5886e to
0697756
Compare
Update🙏 Thank you everyone that has participated so far, I appreciate all the time that you've spent on this and caring enough to give feedback to ensure we get it right. 🦄 Changes from Feedback
I believe that I have addressed all the feedback from each of you that gave a review. Would you mind re-reviewing this PR and let me know if you are happy to approve it. Thank you cc: @osmaczko @micieslak @ilmotta @igor-sirotin @shivekkhurana @friofry @alaibe |
_docs/policies/submitting-policy.md
Outdated
|
|
||
| # Review and Approval Process | ||
|
|
||
| The core function of the review and approval process for policy |
There was a problem hiding this comment.
I feel that the descriptions for each point, while very well written, may add a bit of noise, as they overlap with the README.md or are already clear from the title itself. For this particular point, it seems the 'Collective Agreement' section already covers it well.
There was a problem hiding this comment.
Ok that is fair. How about for this section I replace the description with a new item:
- Reviewers SHOULD keep in mind the principles communicated in
[the README.md](README.md)
There was a problem hiding this comment.
Hm, perhaps we could include a mention of README.md under the Purpose section? For example: "For a more detailed description, please refer to the README.md." This would then implicitly apply to all points.
_docs/policies/submitting-policy.md
Outdated
| - At least one team lead from the Status Desktop or Mobile teams, AND | ||
| - At least one member of the @status-im/status-go-guild GitHub team. |
There was a problem hiding this comment.
Would it make sense to follow the form from "Review and approval process" for consistency?
- Before proceeding, the override:
- MUST be approved by at least one team lead (of Status Desktop and Mobile).
- MUST be approved by at least one member of the @status-im/status-go-guild
There was a problem hiding this comment.
Ok, that is reasonable. What do you think about the following?
- Before approving the non-policy PR, the override:
- MUST be approved in writing by at least one team lead from the Status Desktop or Mobile teams, AND
- MUST be approved in writing by at least one member of the @status-im/status-go-guild.
There was a problem hiding this comment.
It looks good. Since the policy might not be related to PRs, I would remove the reference to 'non-policy PR.' This approach would cover both PR and non-PR changes, making the policy 0 more flexible.
_docs/policies/submitting-policy.md
Outdated
| - At least one member of the @status-im/status-go-guild GitHub team. | ||
| - In exceptional circumstances if an override MUST be executed | ||
| immediately due to urgency, the action SHOULD be documented as soon | ||
| as possible, and retrospective approval MUST be sought and recorded |
There was a problem hiding this comment.
Can you please elaborate what do you mean by retrospective approval?
There was a problem hiding this comment.
I'm beginning to feel doubt about this point. I wanted to make a provision to allow for flexibility in the case of a truly exceptional case, something where we needed to act immediately and justify the actions after. That is what I mean by retrospective approval, you do the work and merge it quick but after you receive approval and explain what happened and why.
I wonder if this would open the door to abuse though. What do you think? (or anyone else)
There was a problem hiding this comment.
I believe approval from one team lead and one member of status-go-guild covers the exceptional cases to be honest - meaning no retrospective approval.
_docs/policies/submitting-policy.md
Outdated
| - The rationale for taking this action, | ||
| - The potential risks and impacts of the override, and | ||
| - Steps taken to minimise those risks. | ||
| - Before proceeding, the override MUST be approved in writing in the |
There was a problem hiding this comment.
I am wondering whether "in writing" is really needed? Wouldn't PR approval be enough?
There was a problem hiding this comment.
Explicitly acknowledging that you approve the PR to breaking one or more policy items creates a document trail that records that the override approvers were not just approving the PR, they were also specifically approving the override.
I'm imagining a case where someone approves a PR that is circumventing a policy, the approval itself doesn't communicate that the approver knew they were also approving the override.
I am overthinking this? Am I missing something?
There was a problem hiding this comment.
That's good point, you are right. The more explicit the approval of exception the better.
_docs/policies/submitting-policy.md
Outdated
| - The potential risks and impacts of the override, and | ||
| - Steps taken to minimise those risks. | ||
| - Before proceeding, the override MUST be approved in writing in the | ||
| circumventing feature PR by: |
There was a problem hiding this comment.
I believe there might be some policies unrelated to PRs 🤔 A very abstract example could be something like a 'GitHub teams management policy' - not the best example, but I hope you get my point.
There was a problem hiding this comment.
This is a good point, what about replace "feature PR" with "non-policy PR"? I'm trying to communicate that the overriding PR is not another policy PR.
| circumventing feature PR by: | |
| circumventing non-policy PR by: |
Let me know if I am not getting your point.
There was a problem hiding this comment.
Perhaps I should add a new item?
- A policy MUST not override an other policy
There was a problem hiding this comment.
What I meant is that policy can be in theory violated not necessarily by code (aka no PR triggered). I don't have many examples in my mind, but would be great to keep policy 0 generic enough to allow such cases.
There was a problem hiding this comment.
LGTM
good to have such policy process defined, nice initiative @Samyoul .
There was a problem hiding this comment.
Thank you for your effort. I hope for there won't be too much policies and hard to understand just like reading a law, yet I look forward to the implementation of knowledge sharing in doc and guidelines after this. @Samyoul
Summary
This pull request introduces Policy Zero, the foundational policy for creating, reviewing, and maintaining all policies in the
status-goGit repository. Policy Zero establishes clear guidelines to ensure a collaborative, inclusive, and transparent process for defining and evolving repository policies. It sets the tone for a consensus-driven approach to repository governance.Purpose
Policy Zero serves as the cornerstone for all subsequent policies by defining:
How policies are proposed:
Review and approval processes:
Policy amendments and archival:
Key Details
Submitting Policies:
_docs/policiesdirectory.Review Process:
Amendments and Archival:
Implementation Notes
000-submitting-policy.mdin_docs/policies.Request for Reviewers
We encourage all Core Contributors, team leads, and status-go Guild members to review this PR. Your feedback will ensure the policy reflects the values of the
status-gocommunity and establishes a strong foundation for future policies.Next Steps
Upon approval, Policy Zero will guide the submission and governance of all future policies in the
status-gorepository. This ensures a standardised, inclusive, and transparent process moving forward.