From a2acc1bbc04b8c31c0a8eba1fc834cf45130926f Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 6 Oct 2022 10:24:40 +0200 Subject: [PATCH 01/11] add RFC process --- rfcs/0000-template.md | 64 ++++++++++++++++++++++++++++ rfcs/README.md | 98 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 rfcs/0000-template.md create mode 100644 rfcs/README.md diff --git a/rfcs/0000-template.md b/rfcs/0000-template.md new file mode 100644 index 0000000000..287c9e340f --- /dev/null +++ b/rfcs/0000-template.md @@ -0,0 +1,64 @@ +- Start Date: (fill me in with today's date, YYYY-MM-DD) +- RFC PR: (fill after opening the PR) +- Github Issue: + +# Summary + +Brief explanation of the feature. + +# Basic example + +When applicable, write a snippet of code showing how the new feature would +be used. + +# Motivation + +Why are we doing this? What use cases does it support? What is the expected +outcome? + +Please focus on explaining the motivation so that if this RFC is not accepted, +the motivation could be used to develop alternative solutions. In other words, +enumerate the constraints you are trying to solve without coupling them too +closely to the solution you have in mind. + +# Detailed design + +This is the bulk of the RFC. Explain the design in enough detail for somebody +familiar with Haystack to understand, and for somebody familiar with the +implementation to implement. This should get into specifics and corner-cases, +and include examples of how the feature is used. Any new terminology should be +defined here. + +# Drawbacks + +Why should we *not* do this? Please consider: + +- implementation cost, both in term of code size and complexity +- whether the proposed feature can be implemented as a separate package, outside of Haystack +- the impact on teaching people Haystack +- integration of this feature with other existing and planned features +- cost of migrating existing Haystack pipelines (is it a breaking change?) + +There are tradeoffs to choosing any path. Attempt to identify them here. + +# Alternatives + +What other designs have been considered? What is the impact of not doing this? + +# Adoption strategy + +If we implement this proposal, how will existing Haystack users adopt it? Is +this a breaking change? Can we write a migration script? + +# How we teach this + +Would the acceptance of this proposal mean the documentation must be re-organized +or altered? Does it change how Haystack is taught to new developers at any level? + +How should this feature be taught to existing Haystack users (e.g. a page in the docs, +a tutorial, ...). + +# Unresolved questions + +Optional, but suggested for first drafts. What parts of the design are still +TBD? \ No newline at end of file diff --git a/rfcs/README.md b/rfcs/README.md new file mode 100644 index 0000000000..228bfa36d6 --- /dev/null +++ b/rfcs/README.md @@ -0,0 +1,98 @@ +# Haystack RFCs + +Most of the changes to Haystack, including buf fixes and small improvements, +are implemented through the normal Pull Request workflow, according to our +[contribution guidelines](../CONTRIBUTING.md). + +Some changes though are "substantial", and those will be put through a bit +of a design process in order to produce a consensus before investing time +into the actual implementation of a new feature or a deep refactoring. + +The RFC (request for comments) design process is intended to provide a +consistent and controlled path for such changes to Haystack. + +We will apply the same level of rigour both to core developers RFCs and +Community RFCs. The primary difference between them is in the design phase: +core developers RFCs tend to be submitted at the end of the design process +whereas the Community RFCs tend to be submitted at the beginning as a way +to kickstart it. + +## When you need to follow this process + +You need to follow this process if you intend to make "substantial" changes to +Haystack, `rest_api` or `ui`, or the RFC process itself. What constitutes a +"substantial" change is evolving based on community norms and varies depending +on what part of the project you are proposing to change, but may include the following: + +- A new feature that creates new API surface areas. +- A new component (Nodes, Pipelines, Document Stores). +- The removal of features that already shipped in the current minor version. +- A deep refactoring that would require new tests or introduce new dependencies +- A change complex enough that would require multiple steps to be delivered + +Some changes do not require an RFC: + +- Rephrasing, reorganizing, or otherwise "changing shape does not change meaning". +- Addition and removal of warnings or other error messages. +- Additions only likely to be noticed by other contributors, invisible to Haystack users. + +In any case, the core developers might politely ask you to submit an RFC before merging +a new feature when they see fit. + +## Before creating an RFC + +A hastily-proposed RFC can hurt its chances of acceptance. Low quality proposals, proposals +for previously-rejected features, or those that don't fit into the near-term +[roadmap](https://github.com/orgs/deepset-ai/projects/3), may be rejected, which can be +demotivating for the new contributor. Laying some groundwork ahead of the RFC can make the +process smoother. + +Although there is no single way to prepare for submitting an RFC, it is generally a good idea +to pursue feedback from other project developers beforehand, to ascertain that the RFC may be +desirable; having a consistent impact on the project requires concerted effort toward +consensus-building. + +Preparations for writing and submitting an RFC include talking the idea over on our official +[Discord server](https://haystack.deepset.ai/community/join), discussing the topic on a Github +issue or discussion in the [Haystack repository](https://github.com/deepset-ai/haystack). + +## What the process is + +In short, to get a major feature added to Haystack, one usually first gets the RFC merged into +the RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with +the goal of eventual inclusion into the Haystack codebase. + +- Copy `0000-template.md` to `text/0000-my-feature.md`, where 'my-feature' is descriptive. Don't assign an RFC number yet. +- Fill in the RFC. Put care into the details: RFCs that do not present convincing motivation, demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly-received. +- Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response. +- Rename the file using the PR number, e.g. from `text/0000-my-feature.md` to `text/4242-my-feature.md`. +- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. +- Eventually, the core developers will decide whether the RFC 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. +- RFCs that are candidates for inclusion in Haystack will enter a "final comment period" lasting 3 calendar days. The beginning of this period will be signaled with a comment and label on the RFCs pull request. +- An RFC can be modified based upon feedback from the core developers and community. Significant modifications may trigger a new final comment period. +- An RFC may be rejected by the core developers after public discussion has settled and comments have been made summarizing the rationale for rejection. A core developer should then close the RFCs associated pull request. +- An RFC may be accepted at the close of its final comment period. A core developer will merge the RFCs associated pull request, at which point the RFC will become 'active'. + +## The RFC lifecycle + +Once an RFC becomes active, then authors may implement it and submit the feature as a pull request +to the Haystack repo. Becoming 'active' is not a rubber stamp, and in particular still does not mean +the feature will ultimately be merged; it does mean that the core team has agreed to it in principle +and are amenable to merging it. + +Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what +priority is assigned to its implementation, nor whether anybody is currently working on it. + +Modifications to active RFCs can be done in followup PRs. We strive to write each RFC in a manner that +it will reflect the final design of the feature; but the nature of the process means that we cannot +expect every merged RFC to actually reflect what the end result will be at the time of the next release; +therefore we try to keep each RFC document somewhat in sync with the feature as planned, tracking such +changes via followup pull requests to the document. + +The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) +is welcome to post an implementation for review after the RFC has been accepted. + +## Inspiration + +React's RFC process owes its inspiration to the [React](https://github.com/reactjs/rfcs) and +[Rust](https://github.com/rust-lang/rfcs) RFC processes. We're open to change it if needed. \ No newline at end of file From 4f7b6c2a7a2125c91125d54c81fbf14193972530 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 6 Oct 2022 10:24:58 +0200 Subject: [PATCH 02/11] migrate old ADR to the new process --- docs/decisions/adr-template.md | 74 ------------------- .../text/2170-pydantic-dataclasses.md | 18 +++-- 2 files changed, 10 insertions(+), 82 deletions(-) delete mode 100644 docs/decisions/adr-template.md rename docs/decisions/pydantic-dataclasses.md => rfcs/text/2170-pydantic-dataclasses.md (89%) diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md deleted file mode 100644 index c07ff84693..0000000000 --- a/docs/decisions/adr-template.md +++ /dev/null @@ -1,74 +0,0 @@ -# {short title of solved problem and solution} - -* Status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} -* Deciders: {list everyone involved in the decision} -* Date: {YYYY-MM-DD when the decision was last updated} - -Technical Story: {description | ticket/issue URL} - -## Context and Problem Statement - -{Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.} - -## Decision Drivers - -* {driver 1, e.g., a force, facing concern, …} -* {driver 2, e.g., a force, facing concern, …} -* … - -## Considered Options - -* {option 1} -* {option 2} -* {option 3} -* … - -## Decision Outcome - -Chosen option: "{option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. - -### Positive Consequences - -* {e.g., improvement of quality attribute satisfaction, follow-up decisions required, …} -* … - -### Negative Consequences - -* {e.g., compromising quality attribute, follow-up decisions required, …} -* … - -## Pros and Cons of the Options - -### {option 1} - -{example | description | pointer to more information | …} - -* Good, because {argument a} -* Good, because {argument b} -* Bad, because {argument c} -* … - -### {option 2} - -{example | description | pointer to more information | …} - -* Good, because {argument a} -* Good, because {argument b} -* Bad, because {argument c} -* … - -### {option 3} - -{example | description | pointer to more information | …} - -* Good, because {argument a} -* Good, because {argument b} -* Bad, because {argument c} -* … - -## Links - -* {Link type} {Link to ADR} -* … - - diff --git a/docs/decisions/pydantic-dataclasses.md b/rfcs/text/2170-pydantic-dataclasses.md similarity index 89% rename from docs/decisions/pydantic-dataclasses.md rename to rfcs/text/2170-pydantic-dataclasses.md index 0b72b8ffaa..d9b6fefeae 100644 --- a/docs/decisions/pydantic-dataclasses.md +++ b/rfcs/text/2170-pydantic-dataclasses.md @@ -1,16 +1,18 @@ -# Dataclasses + +- Start Date: 2021-10-14 +- RFC PR: n/a +- Github Issue: https://github.com/deepset-ai/haystack/pull/1598 +- Deciders: @tholor -* Status: accepted -* Deciders: @tholor -* Date: 2021-10-14 - -Technical Story: https://github.com/deepset-ai/haystack/pull/1598 ## Context and Problem Statement Originally we implemented Haystack's primitive based on Python's vanilla `dataclasses`. However, shortly after we realized this causes issues with FastAPI, which uses Pydantic's implementation. We need to decide which version (vanilla Python's or Pydantic's) to use in our codebase. -## Decision Drivers +## Decision Drivers * The Swagger autogenerated documentation for REST API in FastAPI was broken where the dataclasses include non-standard fields (`pd.dataframe` + `np.ndarray`) @@ -72,7 +74,7 @@ else: * https://github.com/deepset-ai/haystack/pull/1598 * https://github.com/deepset-ai/haystack/issues/1593 * https://github.com/deepset-ai/haystack/issues/1582 -* https://github.com/deepset-ai/haystack/pull/1398 +* https://github.com/deepset-ai/haystack/pull/1398 * https://github.com/deepset-ai/haystack/issues/1232 From dba10dcd3146ed5af26df2e3adff4c17d73063be Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 6 Oct 2022 11:34:44 +0200 Subject: [PATCH 03/11] typo --- rfcs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/README.md b/rfcs/README.md index 228bfa36d6..067f6d2b12 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -1,6 +1,6 @@ # Haystack RFCs -Most of the changes to Haystack, including buf fixes and small improvements, +Most of the changes to Haystack, including bug fixes and small improvements, are implemented through the normal Pull Request workflow, according to our [contribution guidelines](../CONTRIBUTING.md). From b4421ac7e309736eaaed61cbff2953fd6234ba09 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 6 Oct 2022 17:34:05 +0200 Subject: [PATCH 04/11] review comments --- rfcs/0000-template.md | 2 +- rfcs/README.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/rfcs/0000-template.md b/rfcs/0000-template.md index 287c9e340f..441595733c 100644 --- a/rfcs/0000-template.md +++ b/rfcs/0000-template.md @@ -1,6 +1,6 @@ - Start Date: (fill me in with today's date, YYYY-MM-DD) - RFC PR: (fill after opening the PR) -- Github Issue: +- Github Issue: (if available, link the issue containing the original request for this change) # Summary diff --git a/rfcs/README.md b/rfcs/README.md index 067f6d2b12..80f71422ea 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -32,6 +32,7 @@ on what part of the project you are proposing to change, but may include the fol Some changes do not require an RFC: +- Minor bug fixes - Rephrasing, reorganizing, or otherwise "changing shape does not change meaning". - Addition and removal of warnings or other error messages. - Additions only likely to be noticed by other contributors, invisible to Haystack users. @@ -75,10 +76,10 @@ the goal of eventual inclusion into the Haystack codebase. ## The RFC lifecycle -Once an RFC becomes active, then authors may implement it and submit the feature as a pull request -to the Haystack repo. Becoming 'active' is not a rubber stamp, and in particular still does not mean -the feature will ultimately be merged; it does mean that the core team has agreed to it in principle -and are amenable to merging it. +Once an RFC becomes active, then authors may 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 does +not mean the feature will ultimately be merged; it does mean that the core team has agreed to it in +principle and are amenable to merging it if the implementation reflects the contents of the RFC. Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what priority is assigned to its implementation, nor whether anybody is currently working on it. From c242d50d602e1de01b759701f49229f3f995039c Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 7 Oct 2022 15:20:51 +0200 Subject: [PATCH 05/11] Apply suggestions from code review Co-authored-by: Agnieszka Marzec <97166305+agnieszka-m@users.noreply.github.com> --- rfcs/0000-template.md | 38 +++++------ rfcs/README.md | 91 +++++++++++++------------- rfcs/text/2170-pydantic-dataclasses.md | 2 +- 3 files changed, 65 insertions(+), 66 deletions(-) diff --git a/rfcs/0000-template.md b/rfcs/0000-template.md index 441595733c..aa5d1219d2 100644 --- a/rfcs/0000-template.md +++ b/rfcs/0000-template.md @@ -1,10 +1,10 @@ - Start Date: (fill me in with today's date, YYYY-MM-DD) -- RFC PR: (fill after opening the PR) +- RFC PR: (fill in after opening the PR) - Github Issue: (if available, link the issue containing the original request for this change) # Summary -Brief explanation of the feature. +Explain the feature briefly. # Basic example @@ -13,49 +13,49 @@ be used. # Motivation -Why are we doing this? What use cases does it support? What is the expected +Give us more background and explanation: Why do we need this feature? What use cases does it support? What's the expected outcome? Please focus on explaining the motivation so that if this RFC is not accepted, -the motivation could be used to develop alternative solutions. In other words, -enumerate the constraints you are trying to solve without coupling them too +the motivation could be used to develop alternative solutions. +Enumerate the constraints you are trying to solve without coupling them too closely to the solution you have in mind. # Detailed design This is the bulk of the RFC. Explain the design in enough detail for somebody familiar with Haystack to understand, and for somebody familiar with the -implementation to implement. This should get into specifics and corner-cases, -and include examples of how the feature is used. Any new terminology should be -defined here. +implementation to implement. Get into specifics and corner-cases, +and include examples of how the feature is used. Also, if there's any new terminology involved, +define it here. # Drawbacks -Why should we *not* do this? Please consider: +Look at the feature from the other side: what are the reasons why we should _not_ work on it? Consider the following: -- implementation cost, both in term of code size and complexity -- whether the proposed feature can be implemented as a separate package, outside of Haystack -- the impact on teaching people Haystack -- integration of this feature with other existing and planned features -- cost of migrating existing Haystack pipelines (is it a breaking change?) +- What's the implementation cost, both in terms of code size and complexity? +- Can the solution you're proposing be implemented as a separate package, outside of Haystack? +- Does it teach people more about Haystack? +- How does this feature integrate with other existing and planned features? +- What's the cost of migrating existing Haystack pipelines (is it a breaking change?)? There are tradeoffs to choosing any path. Attempt to identify them here. # Alternatives -What other designs have been considered? What is the impact of not doing this? +What other designs have you considered? What's the impact of not adding this feature? # Adoption strategy -If we implement this proposal, how will existing Haystack users adopt it? Is +If we implement this proposal, how will the existing Haystack users adopt it? Is this a breaking change? Can we write a migration script? # How we teach this -Would the acceptance of this proposal mean the documentation must be re-organized -or altered? Does it change how Haystack is taught to new developers at any level? +Would implementing this feature mean the documentation must be re-organized +or updated? Does it change how Haystack is taught to new developers at any level? -How should this feature be taught to existing Haystack users (e.g. a page in the docs, +How should this feature be taught to the existing Haystack users (for example with a page in the docs, a tutorial, ...). # Unresolved questions diff --git a/rfcs/README.md b/rfcs/README.md index 80f71422ea..48fc803a31 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -1,38 +1,38 @@ -# Haystack RFCs +# Haystack Requests For Comments (RFCs) Most of the changes to Haystack, including bug fixes and small improvements, are implemented through the normal Pull Request workflow, according to our [contribution guidelines](../CONTRIBUTING.md). -Some changes though are "substantial", and those will be put through a bit -of a design process in order to produce a consensus before investing time +Some changes, though, are "substantial", and these are the ones we want to put through a bit +of a design process to make sure we're all on the same page before we invest the time into the actual implementation of a new feature or a deep refactoring. -The RFC (request for comments) design process is intended to provide a +We've introduced the RFC design process to provide a consistent and controlled path for such changes to Haystack. -We will apply the same level of rigour both to core developers RFCs and +We will apply the same level of rigor to both core developers RFCs and Community RFCs. The primary difference between them is in the design phase: core developers RFCs tend to be submitted at the end of the design process -whereas the Community RFCs tend to be submitted at the beginning as a way +whereas the Community RFCs tend to be submitted at the beginning, as a way to kickstart it. -## When you need to follow this process +## When do I follow the process? -You need to follow this process if you intend to make "substantial" changes to -Haystack, `rest_api` or `ui`, or the RFC process itself. What constitutes a -"substantial" change is evolving based on community norms and varies depending -on what part of the project you are proposing to change, but may include the following: +Follow the RFC process if you intend to make "substantial" changes to +Haystack, `rest_api` or `ui`, or the RFC 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: - A new feature that creates new API surface areas. - A new component (Nodes, Pipelines, Document Stores). -- The removal of features that already shipped in the current minor version. -- A deep refactoring that would require new tests or introduce new dependencies -- A change complex enough that would require multiple steps to be delivered +- Removing features that already shipped in the current minor version. +- A deep refactoring that would require new tests or introduce new dependencies. +- A change that's complex enough to require multiple steps to be delivered. -Some changes do not require an RFC: +Some changes don't require an RFC, for example: -- Minor bug fixes +- Minor bug fixes. - Rephrasing, reorganizing, or otherwise "changing shape does not change meaning". - Addition and removal of warnings or other error messages. - Additions only likely to be noticed by other contributors, invisible to Haystack users. @@ -49,51 +49,50 @@ demotivating for the new contributor. Laying some groundwork ahead of the RFC ca process smoother. Although there is no single way to prepare for submitting an RFC, it is generally a good idea -to pursue feedback from other project developers beforehand, to ascertain that the RFC may be +to collect feedback from other project developers first, to make sure that the RFC is desirable; having a consistent impact on the project requires concerted effort toward consensus-building. -Preparations for writing and submitting an RFC include talking the idea over on our official -[Discord server](https://haystack.deepset.ai/community/join), discussing the topic on a Github +When you're preparing for writing and submitting an RFC, talk the idea over on our official +[Discord server](https://haystack.deepset.ai/community/join) and in a Github issue or discussion in the [Haystack repository](https://github.com/deepset-ai/haystack). -## What the process is +## The process -In short, to get a major feature added to Haystack, one usually first gets the RFC merged into -the RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with -the goal of eventual inclusion into the Haystack codebase. +In short, to get a major feature added to Haystack, you usually first merge the RFC into +the RFC repo as a Markdown file. At that point, the RFC is 'active' and may be implemented with +the goal of eventually including it into the Haystack codebase. -- Copy `0000-template.md` to `text/0000-my-feature.md`, where 'my-feature' is descriptive. Don't assign an RFC number yet. -- Fill in the RFC. Put care into the details: RFCs that do not present convincing motivation, demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly-received. -- Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response. -- Rename the file using the PR number, e.g. from `text/0000-my-feature.md` to `text/4242-my-feature.md`. -- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. -- Eventually, the core developers will decide whether the RFC 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. -- RFCs that are candidates for inclusion in Haystack will enter a "final comment period" lasting 3 calendar days. The beginning of this period will be signaled with a comment and label on the RFCs pull request. -- An RFC can be modified based upon feedback from the core developers and community. Significant modifications may trigger a new final comment period. -- An RFC may be rejected by the core developers after public discussion has settled and comments have been made summarizing the rationale for rejection. A core developer should then close the RFCs associated pull request. -- An RFC may be accepted at the close of its final comment period. A core developer will merge the RFCs associated pull request, at which point the RFC will become 'active'. +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 RFC number yet. +2. Fill in the RFC. Pay attention to details. RFCs 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 RFC 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. RFCs 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 RFC 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. RFCs that are candidates for inclusion in Haystack enter a "final comment period" lasting 3 calendar days. To let you know that your RFC is entering the final comment period, we add a comment and a label to your PR. +8. An RFC 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 an RFC once the public discussion and adding comments are over, adding the reason for rejection. A core developer then closes the PR related to the RFCs. +10. Core developers may accept an RFC at the close of its final comment period. A core developer then merges the PR related to the RFCs. At this point, the RFC becomes 'active'. ## The RFC lifecycle -Once an RFC becomes active, then authors may 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 does -not mean the feature will ultimately be merged; it does mean that the core team has agreed to it in -principle and are amenable to merging it if the implementation reflects the contents of the RFC. +Once an RFC 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 +mean the feature will ultimately be merged; it does mean that the core team has agreed to it in +principle and is open to merging it if the implementation reflects the contents of the RFC. -Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what -priority is assigned to its implementation, nor whether anybody is currently working on it. +The fact that a given RFC has been accepted and is 'active' doesn't imply it has a priority assigned or somebody's currently working on it. -Modifications to active RFCs can be done in followup PRs. We strive to write each RFC in a manner that -it will reflect the final design of the feature; but the nature of the process means that we cannot -expect every merged RFC to actually reflect what the end result will be at the time of the next release; -therefore we try to keep each RFC document somewhat in sync with the feature as planned, tracking such -changes via followup pull requests to the document. +To change an active RFC, open follow-up PRs. Our goal is to write each RFC so that +it reflects the final design of the feature, but the nature of the process means that we cannot +expect every merged RFC to actually reflect what the end result will be at the time of the next release. +That's why we try to keep each RFC document somewhat in sync with the feature as planned, tracking such +changes through follow-up pull requests to the document. -The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) +As the author of an RFC, you're not obligated to implement it. Of course, the RFC author (like any other developer) is welcome to post an implementation for review after the RFC has been accepted. ## Inspiration React's RFC process owes its inspiration to the [React](https://github.com/reactjs/rfcs) and -[Rust](https://github.com/rust-lang/rfcs) RFC processes. We're open to change it if needed. \ No newline at end of file +[Rust](https://github.com/rust-lang/rfcs) RFC processes. We're open to changing it if needed. \ No newline at end of file diff --git a/rfcs/text/2170-pydantic-dataclasses.md b/rfcs/text/2170-pydantic-dataclasses.md index d9b6fefeae..9cb91fe54a 100644 --- a/rfcs/text/2170-pydantic-dataclasses.md +++ b/rfcs/text/2170-pydantic-dataclasses.md @@ -1,5 +1,5 @@ - Start Date: 2021-10-14 From 306559f9e8f1120122e751a565b4621e5f3a9251 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 7 Oct 2022 15:38:02 +0200 Subject: [PATCH 06/11] [skip ci] review feedback --- rfcs/0000-template.md | 6 ++---- rfcs/README.md | 17 ++++++++--------- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/rfcs/0000-template.md b/rfcs/0000-template.md index aa5d1219d2..d637083d12 100644 --- a/rfcs/0000-template.md +++ b/rfcs/0000-template.md @@ -16,10 +16,8 @@ be used. Give us more background and explanation: Why do we need this feature? What use cases does it support? What's the expected outcome? -Please focus on explaining the motivation so that if this RFC is not accepted, -the motivation could be used to develop alternative solutions. -Enumerate the constraints you are trying to solve without coupling them too -closely to the solution you have in mind. +Focus on explaining the motivation for this feature. We'd like to understand it, so that even if we don't accept this +RFC, others can use the motivation to develop alternative solutions. # Detailed design diff --git a/rfcs/README.md b/rfcs/README.md index 48fc803a31..eedf3fd833 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -21,7 +21,7 @@ to kickstart it. Follow the RFC process if you intend to make "substantial" changes to Haystack, `rest_api` or `ui`, or the RFC process itself. What we define as a -"substantial" change is evolving based on community norms and +"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. @@ -42,11 +42,7 @@ a new feature when they see fit. ## Before creating an RFC -A hastily-proposed RFC can hurt its chances of acceptance. Low quality proposals, proposals -for previously-rejected features, or those that don't fit into the near-term -[roadmap](https://github.com/orgs/deepset-ai/projects/3), may be rejected, which can be -demotivating for the new contributor. Laying some groundwork ahead of the RFC can make the -process smoother. +Laying some groundwork ahead of the RFC can make the process smoother. Although there is no single way to prepare for submitting an RFC, it is generally a good idea to collect feedback from other project developers first, to make sure that the RFC is @@ -63,8 +59,10 @@ In short, to get a major feature added to Haystack, you usually first merge the the RFC repo as a Markdown file. At that point, the RFC is 'active' and may be implemented with the goal of eventually including it into the Haystack codebase. +To create an RFC: + 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 RFC number yet. -2. Fill in the RFC. Pay attention to details. RFCs that present convincing motivation, demonstrate an understanding of the feature impact, and honestly present the drawbacks and alternatives tend to be received well. +2. Fill in the RFC. Pay attention to details. RFCs 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 RFC 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. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. @@ -72,7 +70,7 @@ the goal of eventually including it into the Haystack codebase. 7. RFCs that are candidates for inclusion in Haystack enter a "final comment period" lasting 3 calendar days. To let you know that your RFC is entering the final comment period, we add a comment and a label to your PR. 8. An RFC 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 an RFC once the public discussion and adding comments are over, adding the reason for rejection. A core developer then closes the PR related to the RFCs. -10. Core developers may accept an RFC at the close of its final comment period. A core developer then merges the PR related to the RFCs. At this point, the RFC becomes 'active'. +10. Core developers may accept an RFC at the close of its final comment period. A core developer then merges the PR related to the RFCs. At this point, the RFC becomes 'active'. ## The RFC lifecycle @@ -81,7 +79,8 @@ requests to the Haystack repo. Becoming 'active' is not a rubber stamp, and in p mean the feature will ultimately be merged; it does mean that the core team has agreed to it in principle and is open to merging it if the implementation reflects the contents of the RFC. -The fact that a given RFC has been accepted and is 'active' doesn't imply it has a priority assigned or somebody's currently working on it. +The fact that a given RFC has been accepted and is 'active' doesn't imply it has a priority assigned or somebody's +currently working on it. To change an active RFC, open follow-up PRs. Our goal is to write each RFC so that it reflects the final design of the feature, but the nature of the process means that we cannot From c041bd81992b3ab29fbb99dd31731d985c877b9f Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 7 Oct 2022 15:39:41 +0200 Subject: [PATCH 07/11] Apply suggestions from code review Co-authored-by: Agnieszka Marzec <97166305+agnieszka-m@users.noreply.github.com> --- rfcs/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rfcs/README.md b/rfcs/README.md index eedf3fd833..5f18ffa718 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -46,8 +46,7 @@ Laying some groundwork ahead of the RFC can make the process smoother. Although there is no single way to prepare for submitting an RFC, it is generally a good idea to collect feedback from other project developers first, to make sure that the RFC is -desirable; having a consistent impact on the project requires concerted effort toward -consensus-building. +is actually needed. As we're an open source community where everyone can impact the project, we all need to make an effort to build consensus. When you're preparing for writing and submitting an RFC, talk the idea over on our official [Discord server](https://haystack.deepset.ai/community/join) and in a Github From 70df8c2d4bc0b8ec9ccfc0763000d3fdcdc1ac43 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 7 Oct 2022 15:59:31 +0200 Subject: [PATCH 08/11] [skip ci] leftover --- rfcs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/README.md b/rfcs/README.md index 5f18ffa718..552ad26871 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -92,5 +92,5 @@ is welcome to post an implementation for review after the RFC has been accepted. ## Inspiration -React's RFC process owes its inspiration to the [React](https://github.com/reactjs/rfcs) and +Haystack's RFC process owes its inspiration to the [React](https://github.com/reactjs/rfcs) and [Rust](https://github.com/rust-lang/rfcs) RFC processes. We're open to changing it if needed. \ No newline at end of file From daffbce8a5a595316ef29080f1c64184a39197a9 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Wed, 9 Nov 2022 19:15:21 +0100 Subject: [PATCH 09/11] rename to proposals --- {rfcs => proposals}/0000-template.md | 6 +- proposals/README.md | 97 +++++++++++++++++++ .../text/2170-pydantic-dataclasses.md | 0 rfcs/README.md | 96 ------------------ 4 files changed, 100 insertions(+), 99 deletions(-) rename {rfcs => proposals}/0000-template.md (91%) create mode 100644 proposals/README.md rename {rfcs => proposals}/text/2170-pydantic-dataclasses.md (100%) delete mode 100644 rfcs/README.md diff --git a/rfcs/0000-template.md b/proposals/0000-template.md similarity index 91% rename from rfcs/0000-template.md rename to proposals/0000-template.md index d637083d12..f1267b7f90 100644 --- a/rfcs/0000-template.md +++ b/proposals/0000-template.md @@ -1,5 +1,5 @@ - Start Date: (fill me in with today's date, YYYY-MM-DD) -- RFC PR: (fill in after opening the PR) +- Proposal PR: (fill in after opening the PR) - Github Issue: (if available, link the issue containing the original request for this change) # Summary @@ -17,11 +17,11 @@ Give us more background and explanation: Why do we need this feature? What use c outcome? Focus on explaining the motivation for this feature. We'd like to understand it, so that even if we don't accept this -RFC, others can use the motivation to develop alternative solutions. +proposal, others can use the motivation to develop alternative solutions. # Detailed design -This is the bulk of the RFC. Explain the design in enough detail for somebody +This is the bulk of the proposal. Explain the design in enough detail for somebody familiar with Haystack to understand, and for somebody familiar with the implementation to implement. Get into specifics and corner-cases, and include examples of how the feature is used. Also, if there's any new terminology involved, diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 0000000000..c347157a1e --- /dev/null +++ b/proposals/README.md @@ -0,0 +1,97 @@ +# Haystack proposals design process + +Most of the changes to Haystack, including bug fixes and small improvements, +are implemented through the normal Pull Request workflow, according to our +[contribution guidelines](../CONTRIBUTING.md). + +Some changes, though, are "substantial", and these are the ones we want to put through a bit +of a design process to make sure we're all on the same page before we invest the time +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: +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: + +- A new feature that creates new API surface areas. +- A new component (Nodes, Pipelines, Document Stores). +- Removing features that already shipped in the current minor version. +- A deep refactoring that would require new tests or introduce new dependencies. +- A change that's complex enough to require multiple steps to be delivered. + +Some changes don't require a proposal, for example: + +- Minor bug fixes. +- Rephrasing, reorganizing, or otherwise "changing shape does not change meaning". +- Addition and removal of warnings or other error messages. +- Additions only likely to be noticed by other contributors, invisible to Haystack users. + +In any case, the core developers might politely ask you to submit a proposal before merging +a new feature when they see fit. + +## Before creating a proposal + +Laying some groundwork ahead of the proposal can make the process smoother. + +Although there is no single way to prepare for submitting a proposal, it is generally a good idea +to collect feedback from other project developers first, to make sure that the change is +is actually needed. As we're an open source community where everyone can impact the project, we all +need to make an effort to build consensus. + +When you're preparing for writing and submitting a proposal, talk the idea over on our official +[Discord server](https://haystack.deepset.ai/community/join) and in a Github +issue or discussion in the [Haystack repository](https://github.com/deepset-ai/haystack). + +## 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 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 + +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 +mean the feature will ultimately be merged; it does mean that the core team has agreed to it in +principle and is open to merging it if the implementation reflects the contents of the proposal. + +The fact that a given proposal has been accepted and is 'active' doesn't imply it has a priority assigned or somebody's +currently working on it. + +To change an active proposal, open follow-up PRs. Our goal is to write each proposal so that +it reflects the final design of the feature, but the nature of the process means that we cannot +expect every merged proposal to actually reflect what the end result will be at the time of the next release. +That's why we try to keep each proposal document somewhat in sync with the feature as planned, tracking such +changes through follow-up pull requests to the document. + +As the author of a proposal, you're not obligated to implement it. Of course, the author (like any other developer) +is welcome to post an implementation for review after the proposal has been accepted. + +## Inspiration + +Haystack's proposals design process process owes its inspiration to the [React](https://github.com/reactjs/rfcs) and +[Rust](https://github.com/rust-lang/rfcs) RFC processes. We're open to changing it if needed. diff --git a/rfcs/text/2170-pydantic-dataclasses.md b/proposals/text/2170-pydantic-dataclasses.md similarity index 100% rename from rfcs/text/2170-pydantic-dataclasses.md rename to proposals/text/2170-pydantic-dataclasses.md diff --git a/rfcs/README.md b/rfcs/README.md deleted file mode 100644 index 552ad26871..0000000000 --- a/rfcs/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Haystack Requests For Comments (RFCs) - -Most of the changes to Haystack, including bug fixes and small improvements, -are implemented through the normal Pull Request workflow, according to our -[contribution guidelines](../CONTRIBUTING.md). - -Some changes, though, are "substantial", and these are the ones we want to put through a bit -of a design process to make sure we're all on the same page before we invest the time -into the actual implementation of a new feature or a deep refactoring. - -We've introduced the RFC 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 RFCs and -Community RFCs. The primary difference between them is in the design phase: -core developers RFCs tend to be submitted at the end of the design process -whereas the Community RFCs tend to be submitted at the beginning, as a way -to kickstart it. - -## When do I follow the process? - -Follow the RFC process if you intend to make "substantial" changes to -Haystack, `rest_api` or `ui`, or the RFC 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: - -- A new feature that creates new API surface areas. -- A new component (Nodes, Pipelines, Document Stores). -- Removing features that already shipped in the current minor version. -- A deep refactoring that would require new tests or introduce new dependencies. -- A change that's complex enough to require multiple steps to be delivered. - -Some changes don't require an RFC, for example: - -- Minor bug fixes. -- Rephrasing, reorganizing, or otherwise "changing shape does not change meaning". -- Addition and removal of warnings or other error messages. -- Additions only likely to be noticed by other contributors, invisible to Haystack users. - -In any case, the core developers might politely ask you to submit an RFC before merging -a new feature when they see fit. - -## Before creating an RFC - -Laying some groundwork ahead of the RFC can make the process smoother. - -Although there is no single way to prepare for submitting an RFC, it is generally a good idea -to collect feedback from other project developers first, to make sure that the RFC is -is actually needed. As we're an open source community where everyone can impact the project, we all need to make an effort to build consensus. - -When you're preparing for writing and submitting an RFC, talk the idea over on our official -[Discord server](https://haystack.deepset.ai/community/join) and in a Github -issue or discussion in the [Haystack repository](https://github.com/deepset-ai/haystack). - -## The process - -In short, to get a major feature added to Haystack, you usually first merge the RFC into -the RFC repo as a Markdown file. At that point, the RFC is 'active' and may be implemented with -the goal of eventually including it into the Haystack codebase. - -To create an RFC: - -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 RFC number yet. -2. Fill in the RFC. Pay attention to details. RFCs 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 RFC 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. RFCs 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 RFC 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. RFCs that are candidates for inclusion in Haystack enter a "final comment period" lasting 3 calendar days. To let you know that your RFC is entering the final comment period, we add a comment and a label to your PR. -8. An RFC 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 an RFC once the public discussion and adding comments are over, adding the reason for rejection. A core developer then closes the PR related to the RFCs. -10. Core developers may accept an RFC at the close of its final comment period. A core developer then merges the PR related to the RFCs. At this point, the RFC becomes 'active'. - -## The RFC lifecycle - -Once an RFC 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 -mean the feature will ultimately be merged; it does mean that the core team has agreed to it in -principle and is open to merging it if the implementation reflects the contents of the RFC. - -The fact that a given RFC has been accepted and is 'active' doesn't imply it has a priority assigned or somebody's -currently working on it. - -To change an active RFC, open follow-up PRs. Our goal is to write each RFC so that -it reflects the final design of the feature, but the nature of the process means that we cannot -expect every merged RFC to actually reflect what the end result will be at the time of the next release. -That's why we try to keep each RFC document somewhat in sync with the feature as planned, tracking such -changes through follow-up pull requests to the document. - -As the author of an RFC, you're not obligated to implement it. Of course, the RFC author (like any other developer) -is welcome to post an implementation for review after the RFC has been accepted. - -## Inspiration - -Haystack's RFC process owes its inspiration to the [React](https://github.com/reactjs/rfcs) and -[Rust](https://github.com/rust-lang/rfcs) RFC processes. We're open to changing it if needed. \ No newline at end of file From eab5744c4c40f8bf116ce1a602e27357ab17b33b Mon Sep 17 00:00:00 2001 From: Malte Pietsch Date: Wed, 9 Nov 2022 23:56:14 -0800 Subject: [PATCH 10/11] Adjust naming --- proposals/text/2170-pydantic-dataclasses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/text/2170-pydantic-dataclasses.md b/proposals/text/2170-pydantic-dataclasses.md index 9cb91fe54a..311a38dc3a 100644 --- a/proposals/text/2170-pydantic-dataclasses.md +++ b/proposals/text/2170-pydantic-dataclasses.md @@ -3,7 +3,7 @@ NOTE: this RFC was imported from a different process and is not compliant with t use it as a reference for new RFCs. --> - Start Date: 2021-10-14 -- RFC PR: n/a +- Proposal PR: n/a - Github Issue: https://github.com/deepset-ai/haystack/pull/1598 - Deciders: @tholor From cb4fc112d51440029b1af5c93994487381f5b59f Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 11 Nov 2022 10:40:21 +0100 Subject: [PATCH 11/11] Update 2170-pydantic-dataclasses.md --- proposals/text/2170-pydantic-dataclasses.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/text/2170-pydantic-dataclasses.md b/proposals/text/2170-pydantic-dataclasses.md index 311a38dc3a..a30f94d827 100644 --- a/proposals/text/2170-pydantic-dataclasses.md +++ b/proposals/text/2170-pydantic-dataclasses.md @@ -1,6 +1,6 @@ - Start Date: 2021-10-14 - Proposal PR: n/a