Update the proposals process (#3718)

* update the proposals process

* add stalebot to manage proposals lifecycle

* typo

* Update 0000-template.md

* clarify PR labelling staying away from implementation details

.github/workflows/stale.yml

@@ -0,0 +1,15 @@
+name: 'Stalebot'
+on:
+ schedule:
+ - cron: '30 1 * * *'
+
+jobs:
+ proposals:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/stale@v6
+ with:
+ only-labels: 'proposal'
+ stale-pr-message: 'This proposal is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 10 days.'
+ days-before-stale: 30
+ days-before-close: 10

proposals/0000-template.md

@@ -1,6 +1,8 @@
-- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- Title: (the title in plain english)
+- Decision driver: (your name here)
+- Start Date: (today's date, in format YYYY-MM-DD)
 - Proposal PR: (fill in after opening the PR)
-- Github Issue: (if available, link the issue containing the original request for this change)
+- Github Issue or Discussion: (only if available, link the original request for this change)
 
 # Summary
 
@@ -59,4 +61,4 @@ a tutorial, ...).
 # Unresolved questions
 
 Optional, but suggested for first drafts. What parts of the design are still
-TBD?
+TBD?

proposals/README.md

@@ -11,18 +11,17 @@ into the actual implementation of a new feature or a deep refactoring.
 We've introduced the "Proposals design process" to provide a
 consistent and controlled path for such changes to Haystack.
 
-We will apply the same level of rigor to both core developers and
-Community proposals. The primary difference between them is in the design phase:
+We will apply the same level of rigor to both core developers' and
+Community's proposals. The primary difference between them is in the design phase:
 core developers proposals tend to be submitted at the end of the design process
 whereas the Community ones tend to be submitted at the beginning, as a way
 to kickstart it.
 
 ## When do I follow the process?
 
-Follow the process if you intend to make "substantial" changes to
-Haystack, `rest_api` or `ui`, or the process itself. What we define as a
-"substantial" change is evolving based on community norms and
-on what part of the project you are proposing to change, but it may include the following:
+Follow the process if you intend to make "substantial" changes to Haystack, `rest_api` or the process itself. What is
+defined as a "substantial" change is evolving based on community norms and on what part of the project you are proposing
+to change, but it may include the following:
 
 - A new feature that creates new API surface areas.
 - A new component (Nodes, Pipelines, Document Stores).
@@ -55,24 +54,48 @@ issue or discussion in the [Haystack repository](https://github.com/deepset-ai/h
 
 ## The process
 
-In short, to get a major feature added to Haystack, you usually first merge the proposal into
-the Haystack repo as a Markdown file. At that point, the proposal is 'active' and may be
-implemented with the goal of eventually including it into the Haystack codebase.
+To get a major feature added to Haystack, you first merge the proposal into the Haystack repo as a Markdown file.
+At that point, the proposal can be implemented and eventually included into the codebase.
+
+There are several people involved in the process:
+- **Decision Driver**: the person creating the proposal. If the Decision Driver is not a core contributor themselves,
+ one will be assigned to the PR and will take care of facilitating the process.
+- **Input Givers**: anybody reviewing or commenting the PR.
+- **Approvers**: the core contributors approving the PR.
+
+During its lifecycle, a proposal can transition between the following states:
+- **Review**: proposal is getting feedback.
+- **Final Comment**: proposal received approval from 3 core contributors; this state must be kept for a grace period of
+ 3 calendar days.
+- **Active**: proposal was approved and merged and can be implemented if not already.
+- **Stale**: proposal didn't get any update in the last 30 days and will be closed after a grace period of 10 days.
+- **Rejected**: proposal was actively rejected and the reasons explained.
+
 
 To create a proposal:
 
-1. Copy `0000-template.md` to `text/0000-my-feature.md`, where 'my-feature' is a descriptive name of the feature you're proposing. Don't assign an identification number yet.
-2. Fill in the proposal. Pay attention to details. Proposals that present convincing motivation, demonstrate an understanding of the feature impact, and honestly present the drawbacks and alternatives tend to be received well.
-3. Submit a pull request. This ensures the document receives design feedback from a larger community. As the author, you should be prepared to revise it in response.
-4. Rename the file using the PR number, for example from `text/0000-my-feature.md` to `text/4242-my-feature.md`.
-5. Reach an agreement with the reviewers and integrate the feedback you got. Proposals that have broad support are much more likely to make progress than those that don't receive any comments.
-6. Now it's time for the core developers to take over and decide whether the proposal is a candidate for inclusion in Haystack. Note that a team review may take a long time, and we suggest that you ask members of the community to review it first.
-7. Proposals that are candidates for inclusion in Haystack enter a "final comment period" lasting 3 calendar days. To let you know that your proposal is entering the final comment period, we add a comment and a label to your PR.
-8. A proposal can be modified based on feedback from the core developers and community. Big changes may trigger a new final comment period.
-9. Core developers may reject a proposal once the public discussion and adding comments are over, adding the reason for rejection. A core developer then closes the related PR.
-10. Core developers may accept a proposal at the close of its final comment period. A core developer then merges the related PR. At this point, the proposal becomes 'active'.
-
-## The proposal lifecycle
+1. Copy `0000-template.md` to `text/0000-my-feature.md`, where 'my-feature' is a descriptive name of the feature you're
+ proposing. Don't assign an identification number yet.
+2. Fill in the proposal. Pay attention to details. Proposals that present convincing motivation,
+ demonstrate an understanding of the feature impact, and honestly present the drawbacks and
+ alternatives tend to be received well.
+3. Submit a pull request. This ensures the document receives design feedback from a larger community,
+ and as the Decision Driver, you should be prepared to revise it in response.
+4. Rename the file using the PR number, for example from `text/0000-my-feature.md` to `text/4242-my-feature.md`. The
+ proposal is now in **Review** state.
+5. Reach an agreement with the Input Givers and integrate the feedback you got. Proposals that have broad support are
+ much more likely to make progress than those that don't receive any comments.
+6. Now it's time for the Approvers to decide whether the proposal is a candidate for inclusion in Haystack. Note that a
+ review from the core contributors may take a long time, and getting early feedback from members of the Community can
+ ease the process.
+7. When the proposal enters the **Final Comment** state (see above), the PR will be marked accordingly, entering a
+ grace period lasting 3 calendar days during which a proposal can be modified based on feedback from core developers
+ or the Community. Big changes may trigger a new final comment period.
+8. Approvers may reject a proposal once the public discussion and adding comments are over, adding the reason for
+ rejection. A core developer then closes the related PR. The proposal gets the **Rejected** state.
+9. When the final comment period ends, the PR is merged and the proposal becomes **Active**.
+
+## What happens next
 
 Once a proposal becomes active, the authors are free to implement it and submit the feature as one or more pull
 requests to the Haystack repo. Becoming 'active' is not a rubber stamp, and in particular still doesn't