docs(policy)_: Introduction of policy zero #6165
Conversation
Jenkins BuildsClick to see older builds (38)
|
Samyoul
force-pushed
the
policy/policy-zero
branch
from
85efbd3 to
5d7cf41
Compare
Samyoul
force-pushed
the
policy/policy-zero
branch
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 60.93% 60.91% -0.03%
===========================================
Files 830 830
Lines 109807 109807
===========================================
- Hits 66908 66885 -23
- Misses 35050 35077 +27
+ Partials 7849 7845 -4
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 👀
|
|
||
| # 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.
What is the meaning of "status-go community"? I ask that because I see status-go as simply a repo, a very important one, but still a repo. A community means a lot more. I don't see myself as a member of a status-go community, I see myself as part of the Status community.
There was a problem hiding this comment.
That is a very fair question. I wanted to capture the meaning of "all contributors that want a voice about the way the repo works, that includes core contributors and external contributors."
@ilmotta What do you think about this:
| 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. | |
| 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 among all contributors who wish to have a voice in how the repository operates, including both core contributors and external contributors. 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.
At least to me, your suggestion is an improvement @Samyoul
I remember seeing a few references to the word community in the policy, apart from this one.
| # 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.
| - Policy ideas SHOULD be discussed with Core Contributors (CCs) and other community members. | ||
| - All policies MUST be submitted to the `_docs/policies` directory as a pull request (PR) within the `status-go` repository. | ||
| - All policies MUST be in Markdown format | ||
| - Policy file names MUST follow [File name conventions for ADRs](https://github.com/joelparkerhenderson/architecture-decision-record?tab=readme-ov-file#file-name-conventions-for-adrs), e.g. `000-submitting-policy.md` |
There was a problem hiding this comment.
I'm very sorry for this confusion, which I brought to you.
The 000- prefix doesn't follow the ADR standard. It was my proposal if we should use the counter prefix or go with full accordance with ADR.
At this point I believe it's better to follow the standard and not make up our own one 😄
| - Policy file names MUST follow [File name conventions for ADRs](https://github.com/joelparkerhenderson/architecture-decision-record?tab=readme-ov-file#file-name-conventions-for-adrs), e.g. `000-submitting-policy.md` | |
| - Policy file names MUST follow [File name conventions for ADRs](https://github.com/joelparkerhenderson/architecture-decision-record?tab=readme-ov-file#file-name-conventions-for-adrs), e.g. `submitting-policy.md` |
|
|
||
| # 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.
|
|
||
| # Policy Amendments and Archival | ||
|
|
||
| Policies can be amended or archived to ensure they remain relevant and aligned with community needs. |
There was a problem hiding this comment.
Same here, this summarises (therefore duplicates) what's written further.
But this one is so short and constructive that I actually even like it a bit 😄
| - **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.
igor-sirotin
changed the title
|
|
||
| - **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.
|
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?"
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 |
|
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.