Skip to content

changelog: User experience-oriented recommendations #8996

@thanethomson

Description

@thanethomson

Given the highly technical nature of Tendermint as a product, the changelog is one of our most important communication mechanisms with users and deserves a little more attention going forward.

  1. We should, at the very least, add summaries for every release, with those summaries highlighting what we know to be important to users in that release.
  2. We should document some practices that can help us to better capture the essence of changes from users' perspectives so that it's not necessary to go read the code associated with a changelog entry to even get a faint sense of what the changelog entry's about.

If a changelog entry is obscure/esoteric, and its associated PR is light on details in the description, the only way for a user to understand the entry is to go read the code in the PR. In that case, what's the point of the changelog? They may as well just go read through the Git commit history.

Metadata

Metadata

Assignees

Labels

C:docsComponent: DocumentationT:uxType: Issue or Pull Request related to developer experience

Type

No type

Projects

Status

Done/Merged

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions