Repository navigation
Update list of changelogs - #2232
Conversation
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.
There was a problem hiding this comment.
I haven't heard any feedback from readers yet, so I can only imagine. Given that, I guess anyone coming to the repo to read changelogs has minimal familiarity with the repos and can follow the structure. I could be something like this:
- User interface
- Central app
- Web Forms app
- Client library
- Xforms engine library
- Xpath library
- API
- Infrastructure
There was a problem hiding this comment.
I made a couple of the changes here:
- I changed "Frontend" to "User interface" (in 18de6ea)
- I moved "API" below "User interface" (in e6cad65)
I feel like just those changes would be an improvement over the status quo.
In terms of using more human-readable terms for the subitems of "User interface" (e.g., "Client library" instead of packages/web-forms), I tend to agree with @garethbowen's comment below that it's hard to choose names that convey the concepts clearly. E.g., "Client library" is more human-readable than packages/web-forms, but it probably still wouldn't be clear to most users what the difference is between "Client library" and "Xforms engine library".
In other words, I like the idea of the top-level items being human-readable, but I'm OK with the subitems being the names of the packages/apps. What do you think?
I also added a comment to make it clear that "User interface" is composed of multiple parts, so the user may need to look at multiple changelogs.
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.
There was a problem hiding this comment.
I tried naming them and realised they're just conceptually difficult.
That makes a lot of sense to me. 👍 Especially the seams between the different packages/apps. Rather than trying to get the user to understand those, I like the idea of just telling them what they need to do / what they need to look at. I added a note along those lines to try to make it clear that currently they need to look at multiple changelogs (in d477d56).
What do you think about rolling the changelogs up into either one (frontend) or two (central frontend and web forms)?
Rolling them up sounds nice in terms of the experience of users looking at changelogs. I'm a little wary of creating extra work for ourselves though. Most users won't be looking at the detailed changelogs. I think it's OK if they have to click into a few different changelogs.
If we were to roll them up, I don't have a strong preference between one or two. I can kind of see it both ways.
This could either be done by manually selecting
apps/formsevery time we generate a changeset for web-forms packages
If you all want to start doing that, I certainly don't have an objection. Practically speaking though, since it'd be done manually, I feel like omissions would be possible.
OR in a script somehow.
That's an interesting idea. We already run npm run version as part of the release. We could run a script right after that, or run a script that runs npm run version + does the additional changelog merging/combining. Would you be interested in writing that script? It's probably not something I'd get to right away.
In terms of next steps, maybe we could try to get this PR merged first, then file a follow-up issue about a script?
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.