feat: add reno to manage release notes (#5397)

* first draft

* add release notes

* remove old settings

* add reno usage instructions

* page the docs team when release notes are added

* add reno to the dev dependencies

* Apply suggestions from code review

Co-authored-by: Stefano Fiorucci <44616784+anakin87@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Daria Fokina <daria.fokina@deepset.ai>

---------

Co-authored-by: Stefano Fiorucci <44616784+anakin87@users.noreply.github.com>
Co-authored-by: Daria Fokina <daria.fokina@deepset.ai>

.github/CODEOWNERS

@@ -4,7 +4,8 @@
 # in the repo. Unless a later match takes precedence,
 # @deepset-ai/core-engineering will be requested for review
 # when someone opens a pull request.
-*            @deepset-ai/core-engineering
+*                       @deepset-ai/core-engineering
 
 # Documentation
-*.md         @deepset-ai/documentation @deepset-ai/core-engineering
+*.md                    @deepset-ai/documentation @deepset-ai/core-engineering
+releasenotes/notes/*    @deepset-ai/documentation @deepset-ai/core-engineering

CONTRIBUTING.md

@@ -92,6 +92,7 @@ Note: pre-commit hooks might fail. If that happens to you and you can't understa
 - In case of further issues pushing your changes, please uninstall the hook with `pre-commit uninstall -t pre-commit -t pre-push` and review your Git setup.
 
 ## Proposing "Substantial" Changes
+
 Most of the changes to Haystack, including bug fixes and small improvements, are implemented through the normal Pull Request workflow, according to these  contribution guidelines.
 
 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.
@@ -104,7 +105,9 @@ Please check the [Proposals design process](/proposals) if you think your contri
 - 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.
 
-## Formatting of Pull Requests
+## Requirements for Pull Requests
+
+To ease the review process, please follow the instructions in this paragraph when creating a Pull Request.
 
 ### PR Title
 We use elements from the [conventional commit convention](https://www.conventionalcommits.org/en/v1.0.0/) for our
@@ -141,6 +144,32 @@ for describing and documenting your changes:
 - Breaking changes (Example of before vs. after)
 - How did you test the change?
 
+### Release notes
+Each PR should include a file under the `releasenotes/notes` path created with `reno`, unless the PR doesn't have any
+impact on Haystack behavior, for example: tests and documentation updates, changes in code comments or docstrings,
+changes to the CI/CD systems. PRs that don't require a release note file must be labeled with `ignore-for-release-notes`
+by a maintainer in order to bypass the CI check.
+
+Say your PR is for bumping the `transformers` version in the `pyproject.toml` file. To create the corresponding release
+note, from the root of the repo run:
+```
+$ reno new bump-transformers-to-4-31
+loaded configuration file ./releasenotes/config.yaml
+Created new notes file in releasenotes/notes/bump-transformers-to-4-31-a645334d57eab673.yaml
+```
+`reno` will create the file appending a unique id to the name of the release note you provided (in this case,
+`bump-transformers-to-4-31`). You don't need to worry about duplicated entries, but be sure to use meaningful names
+so it's easier to find the file later. You can now edit the file to add the release note. In the file, you will find multiple
+sections along with an explanation of what they're for. Normally, you only need to fill one section; in this case, you
+would fill the `enhancements` section to describe the change:
+```yaml
+enhancements:
+  - |
+    Upgrade transformers to the latest version 4.31.0 so that Haystack can support the new LLama2 models.
+```
+You can now add the file to the git repo and commit your changes. Your release note will be reviewed along with the
+code you changed.
+
 ## CI (Continuous Integration)
 
 We use GitHub Action for our Continuous Integration tasks. This means that, as soon as you open a PR, GitHub will start executing some workflows on your code, like automated tests, linting, formatting, api docs generation, etc.
@@ -178,7 +207,6 @@ root folder would also execute the ui and rest API tests, that require specific
 You can control which tests to run using Pytest markers, let's see how.
 
 ### Running a subset of tests (recommended)
-
 In most cases you rather want to run a **subset of tests** locally that are related to your dev, and the most important
 option to reduce the number of tests in a meaningful way, is to run tests only for a list of **selected document stores**.
 This is possible by adding the `--document_store_type` arg to your `pytest` command (possible values are: `"elasticsearch, faiss, memory, weaviate, pinecone"`).
@@ -224,7 +252,6 @@ pytest -m not slow
 ```
 
 ### Running all the tests
-
 **Important**: If you want to run **all** the tests locally, you'll need **all** document stores running in the background
 before you run the tests. Many of the tests will then be executed multiple times with different document stores.
 
@@ -291,7 +318,6 @@ def test_write_with_duplicate_doc_ids(document_store):
 ```
 
 ### Option 2: The test is only compatible with certain document stores:
-
 Some tests you don't want to run on all possible document stores. Either because the test is specific to one/few doc store(s) or the test is not really document store related and it's enough to test it on one document store and speed up the execution time.
 
 Example:
@@ -304,7 +330,6 @@ def test_update_meta(document_store):
 ```
 
 ### Option 3: The test is not using a `document_store`/ fixture, but still has a hard requirement for a certain document store:
-
 Example:
 ```
 @pytest.mark.elasticsearch
@@ -315,7 +340,6 @@ def test_elasticsearch_custom_fields(elasticsearch_fixture):
                                                 embedding_field="custom_embedding_field")
 ```
 
-
 ## Code format and style
 
 We use [Black](https://github.com/psf/black) to ensure consistent code style, [mypy](http://mypy-lang.org/) for static type checking and
@@ -325,19 +349,16 @@ All checks and autoformatting happen on the CI, so in general you don't need to
 However, should you prefer to execute them locally, here are a few details about the setup.
 
 ### Black
-
 Black runs with no other configuration than increasing line length to 120 characters. Its configuration can be found in `pyproject.toml`.
 
 You can run it with `python -m black .` from the root folder.
 
 ### Mypy
-
 Mypy currently runs with limited configuration options that can be found at the bottom of `pyproject.toml`.
 
 You can run it with `python -m mypy haystack/ rest_api/ ui/` from the root folder.
 
 ### Pylint
-
 Pylint is still being integrated in Haystack. The current exclusion list is very long, and can be found in `pyproject.toml`.
 
 You can run it with `python -m pylint haystack/ rest_api/ ui/ -ry` from the root folder.

pyproject.toml

@@ -218,6 +218,7 @@ dev = [
   "jupytercontrib",
   "watchdog",
   "toml",
+  "reno",
 ]
 
 formatting = [

releasenotes/config.yaml

@@ -0,0 +1,45 @@
+default_branch: main
+collapse_pre_releases: true
+template: |
+  ---
+  prelude: >
+      Replace this text with content to appear at the top of the section for this
+      release. This is equivalent to the "Highlights" section we used before.
+      The prelude might repeat some details that are also present in other notes
+      from the same release, that's ok. Not every release note requires a prelude,
+      use it only to describe major features or notable changes.
+  upgrade:
+    - |
+      List upgrade notes here, or remove this section.
+      Upgrade notes should be rare: only list known/potential breaking changes,
+      or major changes that require user action before the upgrade.
+      Notes here must include steps that users can follow to 1. know if they're
+      affected and 2. handle the change gracefully on their end.
+  features:
+    - |
+      List new features here, or remove this section.
+  enhancements:
+    - |
+      List new behavior that is too small to be
+      considered a new feature, or remove this section.
+  issues:
+    - |
+      List known issues here, or remove this section. For example, if some change is experimental or known to not work in some cases, it should be mentioned here.
+  deprecations:
+    - |
+      List deprecations notes here, or remove this section. Deprecations should not be used for something that is removed in the release, use upgrade section instead. Deprecation should allow time for users to make necessary changes for the removal to happen in a future release.
+  security:
+    - |
+      Add security notes here, or remove this section.
+  fixes:
+    - |
+      Add normal bug fixes here, or remove this section.
+sections:
+  # The prelude section is implicitly included.
+  - [upgrade, Upgrade Notes]
+  - [features, New Features]
+  - [enhancements, Enhancement Notes]
+  - [issues, Known Issues]
+  - [deprecations, Deprecation Notes]
+  - [security, Security Notes]
+  - [fixes, Bug Fixes]

releasenotes/notes/add-reno-e284cb173ab45ab3.yaml

@@ -0,0 +1,11 @@
+---
+prelude: >
+    Release notes are now managed by `reno`. The main difference is that
+    every contributor is responsible for adding release notes for the feature or bugfix they're
+    introducing in Haystack in the very same Pull Request containing the code changes. The
+    goal is to encourage detailed and accurate notes for every release, especially when it comes
+    to complex features or breaking changes.
+upgrade:
+  - |
+    If you're a Haystack contributor, you need a new tool called `reno` to manage the release notes.
+    Please run `pip install -e .[dev]` to ensure you have `reno` available in your environment.