|
| 1 | +# Cabal Proposals Process |
| 2 | + |
| 3 | +## Motivation |
| 4 | + |
| 5 | +The Cabal project's codebase is large, complex, and has evolved over many years. No single |
| 6 | +person fully understands how all its parts interact. As a result, maintainers |
| 7 | +and contributors often hesitate to make significant changes, unsure whether they |
| 8 | +are safe or whether they align with the project's long-term direction. This |
| 9 | +has led to a delayed decision making process and a tendency to avoid |
| 10 | +making significant decisions. One example is the removal of legacy v1- commands: although most developers agree they should be deprecated and eventually removed, no one feels confident in making that change without a clearer mandate or process. |
| 11 | + |
| 12 | +To address this, we propose a |
| 13 | +lightweight, developer-led process for making and recording significant |
| 14 | +decisions about the future of Cabal and cabal-install. The goal is to enable |
| 15 | +contributors to move the project forward with greater confidence and |
| 16 | +shared understanding. |
| 17 | + |
| 18 | +The process is designed to make developers feel empowered to make decisions. |
| 19 | + |
| 20 | +* It is light-weight, a PR is opened and discussed on a repo with a fixed discussion period. |
| 21 | +* It is developer-led, final decisions are made by developers at the Cabal developers meeting. |
| 22 | +* It is flexible, there is no formal voting procedure, decisions are made by [rough consensus](https://datatracker.ietf.org/doc/html/rfc7282). |
| 23 | + |
| 24 | +Overall, we hope that this will allow developers to move the cabal project forward. |
| 25 | + |
| 26 | +This process is an experiment. We will review it over time to ensure that it continues to serve the Cabal project well. |
| 27 | + |
| 28 | +## Principles |
| 29 | + |
| 30 | +- The process exists to support active contributors, not to control them. |
| 31 | +- The decision-making power remains with those who contribute code and maintain the project. |
| 32 | +- The process is deliberately kept lightweight to avoid burdening contributors. |
| 33 | + If contributors do not want to use the process then it should be modified. |
| 34 | +- The developers meeting will assess consensus to make a final decisions. |
| 35 | +- Transparency and documentation make it easier for all contributors to follow significant decisions. |
| 36 | + |
| 37 | + |
| 38 | +## Scope |
| 39 | + |
| 40 | +This process applies to: |
| 41 | + |
| 42 | +- Changes to the `Cabal` library. |
| 43 | +- Changes to the `cabal-install` tool. |
| 44 | +- Significant process or tooling changes for the Cabal project itself. |
| 45 | + |
| 46 | +This process does **not** apply to: |
| 47 | + |
| 48 | +- The broader Haskell ecosystem. |
| 49 | +- Community-wide standards. |
| 50 | +- Individual packages not maintained in the Cabal project. |
| 51 | + |
| 52 | +Routine or small changes do not require a formal proposal; they can continue to be discussed and merged via the normal PR process. |
| 53 | + |
| 54 | +### Examples |
| 55 | + |
| 56 | +* Bug fixes or small improvements do not require proposals. |
| 57 | +* Improving features which already see wide agreement does not require proposals (for example, migrating existing commands from v1- to v2-). |
| 58 | +* Larger features should be first discussed on a proposal (for example, a new command, Hooks, private dependencies). |
| 59 | +* Significant changes to existing behaviour should be discussed on proposals. |
| 60 | + |
| 61 | +In general, most changes do not require proposals, developers are trusted to use their judgement about when seeking a broader consensus is necessary. |
| 62 | + |
| 63 | +## Process |
| 64 | + |
| 65 | +### 1. Proposal Submission |
| 66 | + |
| 67 | +- Proposals are submitted as **pull requests** to the [`cabal-proposals`](https://github.com/haskell/cabal-proposals) repository. |
| 68 | +- The proposal must follow the [proposal template](#proposal-template). |
| 69 | +- Anyone can submit a proposal. However, proposals without the support of active contributors are unlikely to be accepted. |
| 70 | +- There is a general expectation that authors of proposals will take the lead on their implementation. If proposals remain unimplemented for an extended period, it may affect how future proposals from the same author are received. |
| 71 | + |
| 72 | +### 2. Discussion |
| 73 | + |
| 74 | +- Discussion happens on the pull request. |
| 75 | +- There is a **minimum comment period** of 2 weeks, or until the next Cabal developers meeting (whichever is longer). Extensions may be granted for more complex topics. |
| 76 | +- All community members are welcome to comment. Maintainers and active contributors are especially encouraged to provide feedback. |
| 77 | +- After the minimum comment period, the author can request for the proposal to be decided on at |
| 78 | + the Cabal developers meeting. |
| 79 | + |
| 80 | +### 3. Decision Meeting |
| 81 | + |
| 82 | +- The Cabal developers meeting is the forum for making decisions on proposals. |
| 83 | +- The developers present at the meeting should reflect on the comments on a proposal and determine the [rough consensus](https://datatracker.ietf.org/doc/html/rfc7282) of the community. |
| 84 | + The opinion of knowledgeable contributors regarding a particular subsystem is especially |
| 85 | + important for the meeting to reach a decision. |
| 86 | +- It is not necessarily expected that the participants of the meeting will offer a technical opinion. The discussion on the issue should provide enough context for a decision to be made. |
| 87 | +- There is a quorum of three developers at the meeting. |
| 88 | +- If quorum is not reached for 4 consecutive meetings (8 weeks) whilst a proposal is due to be discussed, the proposal process is suspended and reviewed. |
| 89 | + |
| 90 | +## 4. The Decision |
| 91 | + |
| 92 | +- A proposal is **accepted** if there is general agreement among active maintainers and contributors present at the meeting. |
| 93 | +- A proposal is **rejected** if consensus cannot be reached or the developers do not wish to |
| 94 | + pursue the direction of the proposal. |
| 95 | +- A proposal is **deferred** if the developers generally agree with the direction of the proposal |
| 96 | + but have specific and actionable points which require improvement before acceptance. |
| 97 | + For example, the opinion of a certain expert may be additionally sought or they may wish for more consideration into the backwards compatibility story. |
| 98 | +- The meeting chair is responsible for recording the outcome on the proposal PR. |
| 99 | + |
| 100 | + |
| 101 | +### 5. Outcome and Implementation |
| 102 | + |
| 103 | +- **Accepted** proposals are merged into the `cabal-proposals` repository and tagged as "Accepted". |
| 104 | +- **Rejected** proposals are closed with a clear rationale. |
| 105 | +- **Deferred** proposals may be left open with an explicit milestone for revisiting. |
| 106 | + |
| 107 | +Acceptance of a proposal does not automatically result in implementation. The proposer is expected to implement the change or coordinate with others to do so. |
| 108 | + |
| 109 | +### Example Timeline |
| 110 | + |
| 111 | +* A proposal is opened. |
| 112 | +* A two weeks discussion period follows. |
| 113 | +* After at least two weeks, the author may ask cabal developers to consider their proposal. |
| 114 | +* The cabal developers may decide about the proposal at the next developers' meeting or a cabal developer may ask for a longer discussion period. |
| 115 | +* The proposal is accepted: the proposal author implements the feature. |
| 116 | +* The proposal is rejected: the PR is closed. |
| 117 | +* The proposal is deferred: the decision period is extended and a concrete |
| 118 | + reason for deferral is named. Once the concern has been addressed then the |
| 119 | + proposal is reviewed again at the meeting. |
| 120 | + |
| 121 | + |
| 122 | +## Proposal Template |
| 123 | + |
| 124 | +Each proposal should include the following sections: |
| 125 | + |
| 126 | +```markdown |
| 127 | +# Title |
| 128 | + |
| 129 | +## Summary |
| 130 | + |
| 131 | +A short, high-level summary of the proposed change. |
| 132 | + |
| 133 | +## Motivation |
| 134 | + |
| 135 | +Why is this change needed? What problem does it solve? |
| 136 | + |
| 137 | +## Proposed Change |
| 138 | + |
| 139 | +Describe the change in detail. |
| 140 | + |
| 141 | +## Alternatives Considered |
| 142 | + |
| 143 | +What other approaches were considered? Why was this one chosen? |
| 144 | + |
| 145 | +## Backwards Compatibility / Migration |
| 146 | + |
| 147 | +Does this change affect backwards compatibility? What migration path is needed? |
| 148 | + |
| 149 | +## Interested parties |
| 150 | + |
| 151 | +Who are the interested parties in the broader Haskell community? Have you contacted them? |
| 152 | + |
| 153 | +## Implementation Notes |
| 154 | + |
| 155 | +Are you willing to implement this yourself? What is the expected timeline? |
| 156 | + |
| 157 | +## Open Questions |
| 158 | + |
| 159 | +Are there any unresolved questions or areas needing further input? |
| 160 | + |
| 161 | +## References |
| 162 | + |
| 163 | +Links to related issues, discussions, or previous work. |
| 164 | +``` |
0 commit comments