Who is the changelog for?

[mfisher87]

Is it for end-users, contributors, both? How do we keep the signal-to-noise ratio high? Two changelogs? 🤷

Also...

How will we record this decision permanently? We should have a decision record doc. Do we want that in the earthaccess repo?

We could probably save some effort and rework our decision committee governance process to match Jupyter's decision-making policies. A decision record would live in a "team compass" repo under that model.

[jhkennedy]

We follow Common Changelog, which has two sections that are particularly relevant to this discussion:

1. A changelog is a file that contains a curated, ordered list of notable changes for each versioned release of a project. Its purpose is to make it easier for consumers (and to a lesser extent contributors) to see precisely what changes have been made between two releases.

   The consumers of software are human beings who care about what's in the software. They must be able to quickly understand the impact of a release. Semantic Versioning helps as a signaling mechanism but is not enough by itself. When software changes, people want to know why and how.

   https://common-changelog.org/#11-what-is-a-changelog

2. Exclude maintenance changes that are not interesting to consumers of the project (in its distributed form). To name a few:

   • Dotfile changes (.gitignore, .github, .gitlab and so forth)
   • Changes to development-only dependencies
   • Minor code style changes
   • Formatting changes in documentation.

   However, changes such as the following must not be excluded:

   • Refactorings, which may have unintentional side effects. Let the community review them.
   • Changes to supported runtime environments (which may be reflected only in dotfiles)
   • Code style changes that use new language features
   • New documentation (if a feature was previously undocumented).

   https://common-changelog.org/#32-remove-noise

My mental filter roughly matches that, but is best described by asking these two questions:

1. Would a user want to know this when they upgrade?
2. Would a developer want to know this when they next work on earthaccess?

Which has a slightly different connotation to "consumers" and "audience".

[chuckwondo]

My mental filter roughly matches that, but is best described by asking these two questions:

1. Would a user want to know this when they upgrade?
2. Would a developer want to know this when they next work on earthaccess?

Which has a slightly different connotation to "consumers" and "audience".

My take on this is that as a developer, I'm not going to look to the changelog to give me any meaningful insights into how my development of the library may change over time. Rather, I'm simply going to look at the code and corresponding unit tests, and any internal code comments, or a contributor's guide (if the project has one).

For example, in the case of the change in the integration testing approach, I don't want to see a changelog indicating that "randomness" was removed. Instead, I want to see that reflected in the section of the contrib guide that covers how we have designed the integration tests (if we have such a section). In this case, that might simply mean removing the mention of "randomness" from the guide (possibly with addition of some other wording, as might make sense), since it is no longer used.

Conversely, as a user, I really don't want to read through (or mentally filter out) "internal" changelog entries that simply clutter up the end-user information that I care about for using the library.

[Sherwin-14]

imho its for the users since the commit history is what the devs would refer to.

[jhkennedy]

Alright, I'll concede that I'm the lone voice here advocating for the changelog to include user- and developer-focused entries.

If it's solely user-facing, should we do a bit more with it?

That is, the changelog entries only show up in two places; as a file in the repository and as part of the GitHub releases, both of which are generally only targeting people who are comfortable with GitHub and code.

Since we're a Python library, this probably captures a large chunk of our users, but there is also a sizable segment of our user base who are not coders or just learning to be coders on the science/analyst side of the house.

We don't really provide the changelog to these users because, in our documentation, the only place we discuss the CHANGELOG is on the "Backwards Compatibility" and "Release process" pages. We also don't discuss or link to it from our README.

If we want this to actually be solely end-user focused, I think we should do a bit better getting it to our users by, for example, placing it in our docs prominently on a top-level "What's new" "History" or similar page.

As it stands, to me, it seems like the audience is "the people who look at the code", so our users who are comfortable with code and our developers.

[mfisher87]

That's a really good point, Joe. We should definitely have the CHANGELOG more prominently displayed on the docs site.