Add release changelogs to the docs

[dichotommy]

Release changelogs are pretty standard for API documentation.

Currently, ours are available on GitHub under the releases tab of the main MeiliSearch repository. It would be better to centralize information on the docs, so existing users don't have to travel to GitHub to find the changes.

This has the positive side effect of allowing users to search through our changelogs. On the other hand, many accumulated changelogs can create a lot of "noise" in the search results... we will have to see if this necessitates further action on our MeiliSearch instance.

[bidoubiwa]

Some other documentation release notes:

• Fauna db
• Typescript
• React
• Gatsby

[dichotommy]

@bidoubiwa React's approach is interesting. They maintain a file CHANGELOG.md in their main repo with the changelog for every previous version, and link to it on their docs. They also copy and paste the text from this file into their GitHub release descriptions.

Pros

• Browsers of the docs know where to find changelogs
• Changelogs are subject to version control and have built-in collaborative editing through GitHub
• Changelogs can be viewed offline by anyone who has downloaded the project

Cons

• Users still have to travel away from the docs site and view the information in GitHub's (possibly unfamiliar) UI
• Increasingly large text file added to main project repo
• No single source of truth (this would be CHANGELOG.md, but the text is copied to the GitHub release descriptions, so subsequent changes may require copy+pasting to update)

I wonder if this could be a good approach for us? It would be nice for the docs team to have a more direct route of giving feedback on the release notes, instead of working in a google doc or verbally asking @curquiza to change things since we can't edit the GitHub release body ourselves.

Ultimately though, I think we could accomplish almost the same thing by keeping the changelogs entirely on the docs site and linking to them from the GitHub release body. This would also be more "single source of truth".

[guimachiavelli]

Agree with everything you say here, but your second con is a question that applies to having the changelog on the docs repo too: that text file will always get bigger. Possibly not a huge issue until we're on v129.0.53, though.

A devil's advocate question: could a hardcore user checking the core repo get annoyed at checking the release tab and having to go "all the way" to the docs to get the changelog?

[curquiza]

No single source of truth (this would be CHANGELOG.md, but the text is copied to the GitHub release descriptions, so subsequent changes may require copy+pasting to update)

I'm not a big fan of hard text duplication, especially in two different repos. This involves tech work so I totally understand if "copy/paste the changelog" is the first version of "having the changelog in the documentation", but this will be definitively an issue to fix in the future. We will need to fetch the text of stable releases to generate the changelogs on the documentation side 🙂 Sorry if I miss-understand something

[guimachiavelli]

Yeah, I'm also not a fan of manually copypasting chunks of text, since we will inevitably end up with mismatches between repo and site. @curqui, do you think this could be solved with a github action? Something that gets triggered whenever a file in the docs repo (e.g. changelog.md) and updates the correct text on the releases tab?

[curquiza]

A script called in a GitHub action I would say, or a plugin called during the build of the website.

[szepeviktor]

It is very sad that Meilisearch has no changelog file. Users are forced to browse text uploaded to GitHub releases. It is NOT searchable. You know :) >SEARCH<able. I mean it is okay to be modern but this is so post-modern that makes it impossible to follow development.

[bidoubiwa]

meanwhile their are blog posts in our blog covering most of the changes

[szepeviktor]

meanwhile their are blog posts in our blog covering most of the changes

Thank you for your comment. You must know nice blog posts wont help professionals. A changelog looks like https://downloads.apache.org/httpd/CHANGES_2.4

[bidoubiwa]

Oh yes, I agree that we should have a changelog :) It was just a temporary solution for you

[dichotommy]

Now that we have reached v1 and have a dedicated Update and migration section on the documentation, it is time to reopen this conversation!

It makes more sense than ever to begin hosting changelogs on the docs, starting with v1.0. The main question is how to handle this process.

To get started, we could copy-paste the v1.0 changelog from the releases tab of meilisearch/meilisearch into a new page in the Update and migration section.

Long-term, there are a number of questions we should answer:

• Should the @meilisearch/engine-team change their changelog process from creating PRs in meilisearch/engine-team to creating PRs directly on the documentation? Where should be the single-source of truth?
• Should the releases tab of meilisearch/meilisearch contain the full changelog copy-pasted, or a truncated version? We could even imagine only a brief sentence about the main features of the release followed by a link to the documentation changelog. How do other open-source companies handle this?
• Should changelog file(s) be indexed in the documentation search bar? (Probably not)
• Should the documentation site have a single ever-growing page for all changelogs, or should each changelog have its own page? (I lean towards the former, for CMD + F purposes)

Very interested to have the input of @curquiza and anyone else who has strong feelings about changelogs 😊

[curquiza]

• Should the @meilisearch/engine-team change their changelog process from creating PRs in meilisearch/engine-team to creating PRs directly on the documentation? Where should be the single-source of truth?

The changelogs in engine-team are not considered a source consulted by the users, so I don't consider it as a source of truth, but more archived information. Originally, I was doing the changelogs draft on Notion, and after discussing with @guimachiavelli, we thought we could start to do the draft on GitHub

• to include everyone, even the community
• to review it easily (not convenient on Notion)

However, the docs are consulted by the users, contrary to engine-team repo. And I really don't recommend having two sources of truth: in the docs and the release sections. If, for any reason, we have to change something in the changelogs (it often happens), it's really inconvenient to change it in the docs. I currently don't change the one in engine-team once the release is officially done.

Currently, there is a unique source of truth: the release changelogs on Github.

---

• Should the releases tab of meilisearch/meilisearch contain the full changelog copy-pasted, or a truncated version? We could even imagine only a brief sentence about the main features of the release followed by a link to the documentation changelog. How do other open-source companies handle this?

No opinion on "the truncated notes or full notes?". When I personally want to know the exact changes, I read the changes in the release notes on GitHub. Benchmarks and investigation on the other docs need to be done 😄

⚠️ However, if we go with full notes -> my strong recommendation is we should spend time installing an automated fetching of the changelogs and not copy/paste them. I'm fully against the copy/paste until someone tells me it's not possible 😂 @bidoubiwa maybe you have some clue to do it?

Another possibility could be only to put the release changelogs on the docs side, and only put a link on the GitHub side. But it's not conistent because we also need release notes for the RCs, not only for official releases. And these release's notes (for RCs) will not be on the docs side. So on GitHub, we will have big release notes for RCs, and not for official releases

---

Should changelog file(s) be indexed in the documentation search bar? (Probably not)

Why not? Not as a priority result, but knowing when the feature is present and which version you have to install could be nice. Also looks like the user right here in the issue needs to search in the changelogs.

👉 For me, the goal of introducing release notes into the docs could also be to make some part of the changelogs retrievable (which is indeed impossible with GitHub, and frustrating, even for me).

---

• Should the documentation site have a single ever-growing page for all changelogs, or should each changelog have its own page? (I lean towards the former, for CMD + F purposes)

If we index the data of the changelogs, I vote for multiple pages maybe? But some investigations need to be done. For example PHP is doing 1 page per release, react as well

[szepeviktor]

The main goal is provide a way to keep track of Meilisearch development. Maybe I'm the only person willing to read changelogs daily. It is very important to make it searchable.

Many projects do these

• create GitHub Releases and fill-in release discription
• maintain a CHANGELOG.md file
• maybe splitting that file at every major release ... CHANGELOG-v1.md

[brunoocasali]

Very interested to have the input of @curquiza and anyone else who has strong feelings about changelogs 😊

My feeling is that we should have a CHANGELOG.md in the repository is unbelievably helpful when you're developing. GitHub Releases are very beautiful but useless for me if I want to understand some "whys" across the project's history.

I'm highly in favor of having the file or the full web version to search with CMD+F.

And I also agree with @curquiza regarding the source of truth and copying/pasting it around repos.

[szepeviktor]

There are beautiful solutions https://linear.app/changelog (this one with email notification)

[bidoubiwa]

Hey @curquiza

I played around and creating a dynamic page is an easy process. See this PR as an example

https://github.com/meilisearch/documentation/pull/2162

[curquiza]

@guimachiavelli is this still relevant knowing what we plan for devhub?

[curquiza]

Discussed with @guimachiavelli Indeed, this issue will be solved by the devhub project. If for any reason it does not happen, we will re-open it.