Update list of changelogs - #2232
Conversation
matthew-white
left a comment
matthew-white
left a comment
There was a problem hiding this comment.
Adding notes to facilitate code review.
There was a problem hiding this comment.
I recommend hiding white space when viewing this diff.
| * [packages/web-forms](https://github.com/getodk/central-frontend/blob/master/packages/web-forms/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xforms-engine](https://github.com/getodk/central-frontend/blob/master/packages/xforms-engine/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xpath](https://github.com/getodk/central-frontend/tree/master/packages/xpath/CHANGELOG.md#<version-without-dots>) | ||
| * [API](https://docs.getodk.org/central-api-changelog/) |
There was a problem hiding this comment.
I changed "back-end" to "API" because I think that's the term our users will be more familiar with. It's the one we use more often in user docs.
If we're trying to match the name of the central-backend repository, I'm OK with that. But in that case, I'd want to change it to "backend" and remove the hyphen. We don't generally hyphenate "backend" where we do use the term.
| * [packages/web-forms](https://github.com/getodk/central-frontend/blob/master/packages/web-forms/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xforms-engine](https://github.com/getodk/central-frontend/blob/master/packages/xforms-engine/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xpath](https://github.com/getodk/central-frontend/tree/master/packages/xpath/CHANGELOG.md#<version-without-dots>) | ||
| * [API](https://docs.getodk.org/central-api-changelog/) |
There was a problem hiding this comment.
The API changelog is more readable in docs.getodk.org compared to GitHub, so I think we should link there instead. Example: links are clickable.
| * [packages/xforms-engine](https://github.com/getodk/central-frontend/blob/master/packages/xforms-engine/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xpath](https://github.com/getodk/central-frontend/tree/master/packages/xpath/CHANGELOG.md#<version-without-dots>) | ||
| * [API](https://docs.getodk.org/central-api-changelog/) | ||
| * Frontend |
There was a problem hiding this comment.
I was prompted to make this change after adding the operations infrastructure changelog in #2226. I added that changelog to the bottom of the list, but then it felt a little funny to have a bunch of frontend changelogs sandwiched by non-frontend changelogs, without any grouping of the frontend changelogs.
Other thoughts:
- I could reorder the operations infrastructure changelog right below API/back-end. Then the frontend changelogs wouldn't feel sandwiched. I feel like the frontend changelogs will usually be more interesting to end users though.
- Unless you know Central's architecture well, I don't think it's obvious that apps/central is exclusively about Central Frontend, not the Central application as a whole. Grouping it under "Frontend" would help with that.
- Wording choice: could also say "UI" or "User interface" instead of "Frontend"?
- "Frontend" is a holistic grouping that includes both Central Frontend and Web Forms.
garethbowen
left a comment
garethbowen
left a comment
There was a problem hiding this comment.
Good improvements. A couple of additional ideas inline.
| * [packages/xforms-engine](https://github.com/getodk/central-frontend/blob/master/packages/xforms-engine/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xpath](https://github.com/getodk/central-frontend/tree/master/packages/xpath/CHANGELOG.md#<version-without-dots>) | ||
| * [API](https://docs.getodk.org/central-api-changelog/) | ||
| * Frontend |
There was a problem hiding this comment.
I think most users are interested in Frontend over API, so possibly the order should be Frontend, then API, then Operations?
| * [apps/forms](https://github.com/getodk/central-frontend/tree/master/apps/forms/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/web-forms](https://github.com/getodk/central-frontend/blob/master/packages/web-forms/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xforms-engine](https://github.com/getodk/central-frontend/blob/master/packages/xforms-engine/CHANGELOG.md#<version-without-dots>) | ||
| * [packages/xpath](https://github.com/getodk/central-frontend/tree/master/packages/xpath/CHANGELOG.md#<version-without-dots>) |
There was a problem hiding this comment.
I like the human readable nature of the rest of the items, which made me think these frontend items are very confusing unless you know the internal structure of the repo.
But then I tried naming them and realised they're just conceptually difficult.
What do you think about rolling the changelogs up into either one (frontend) or two (central frontend and web forms)? This could either be done by manually selecting apps/forms every time we generate a changeset for web-forms packages, OR in a script somehow. People who use the individual packages as libraries will still have the individual changelog as well, but the combined release notes will be simpler.
2 participants
This PR updates the list of changelogs in the release template. It intentionally targets the
masterbranch.What has been done to verify that this works as intended?
Nothing in particular. It's just a change to Markdown.
Why is this the best possible solution? Were any other approaches considered?
I'll leave comments about individual decisions I made.
If we like these changes to release.md, I'll also make them to patch_release.md.