docs(policy)_: Introduction of policy zero #6165
Conversation
Jenkins BuildsClick to see older builds (136)
|
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.75% 61.76% +0.01%
===========================================
Files 843 843
Lines 111285 111285
===========================================
+ Hits 68720 68733 +13
+ Misses 34592 34590 -2
+ Partials 7973 7962 -11
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 |
|
Following on from our interaction @fryorcraken, I'd appreciate your input on this policy PR @plopezlpz . Specifically this line: https://github.com/status-im/status-go/pull/6165/files#diff-642a8833af0a32cbf0de25751911b7e61a166e315bae9ee8cf64fa8e9988115fR31 Would you like a requirement or at least a consideration from your team to approve future policies? EDIT: Also would you like to review this PR also? |
| All discussions, decisions, and processes related to policy creation | ||
| must be fully transparent. This includes: | ||
|
|
||
| - **Open documentation**: Discussions leading to policy decisions |
There was a problem hiding this comment.
Would be good to have some guidelines on where you intend to hold these discussions and publish the documentation.
From experience, a lot of discussions are happening in private Discord groups or Discord channels.
There was a problem hiding this comment.
But this clause is specifically about keeping the decisions public 🤔
In general, it will a PR, just like this one. All comments and resolutions are publicly documented.
But the README shouldn't limit it to a specific platform. README document describes the intentions, it's not a policy itself.
At the same time _docs/policies/submitting-policy.md describes that the policy should be a PR and all feedbacl must be resolved. This covers the intentions described in the README.
@fryorcraken does this make sense?
Samyoul
force-pushed
the
policy/policy-zero
branch
from
04ff677 to
2c6f4b8
Compare
Samyoul
force-pushed
the
policy/policy-zero
branch
from
2c6f4b8 to
3bb0a5f
Compare
|
You will need to rebase your branch on |
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
'4. Enforceability and Respect for Policies' with 'Upholding Policies Through Consensus'
Samyoul
force-pushed
the
policy/policy-zero
branch
from
3bb0a5f to
4a412fe
Compare
|
I've just re-rebased, and my HEAD is 
|
Samyoul
force-pushed
the
policy/policy-zero
branch
from
4a412fe to
abb72b9
Compare
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.