-
-
Notifications
You must be signed in to change notification settings - Fork 52
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve readability of CHANGELOGs #261
Comments
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
The CHANGELOGs list the path associated to a change, prior to the summary of the change. The addition of paths to those changes adds very little useful information (if any at all). The decision of how big a part of the path to show in the CHANGELOG (e.g., src/FRP/Yampa.hs vs src/) is quite arbitrary. Adding the paths also implies that, sometimes, a change may have to be listed multiple times, since it affected multiple paths, and the re-wrapping of change summaries to fit in one line makes for awkward diffs and makes reading the CHANGELOGs harder. This commit removes the paths from the entries in Yampa's CHANGELOG, and reformats the entries to be one per line. Because the removal of the path also removes some context from each entry, some entries are adjusted to better reflect the change. Whenever needed, the summary from the accompanying issue on github is used to re-phrase the entry.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
The CHANGELOGs current list each release in a separate group. To facilitate reading the groups, we want to stick to a standard format as much as possible. This change moves the version bump associated to each group of entries in Yampa's changelog to the top of each group.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
Re-format references to issues to conform to the style used elsewhere in the CHANGELOG.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
The CHANGELOGs current list each release in a separate group, prefaced by the maintainer's details and release date. Sometimes, a space is left after the maintainer's details and sometimes no space is left. To facilitate reading the groups, we want to stick to a standard format as much as possible. This commit removes that space for each group, which makes it clearer that the group of entries follow the preceding release date line.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
Reduce indentation in the file to 4 spaces to make more space, reduce line wraps, and make the file easier to read.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
To aid in reading the file, fix existing typo.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
To standardize the format of the entries in the CHANGELOG, express all of them as imperative commands, as opposed to past-tense or in the third-person.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
The CHANGELOGs list the path associated to a change, prior to the summary of the change. The addition of paths to those changes adds very little useful information (if any at all). The decision of how big a part of the path to show in the CHANGELOG (e.g., src/FRP/Yampa.hs vs src/) is quite arbitrary. Adding the paths also implies that, sometimes, a change may have to be listed multiple times, since it affected multiple paths, and the re-wrapping of change summaries to fit in one line makes for awkward diffs and makes reading the CHANGELOGs harder. This commit removes the paths from the entries in yampa-test's CHANGELOG, and reformats the entries to be one per line.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
Reduce indentation in the file to 4 spaces to make more space, reduce line wraps, and make the file easier to read.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
To standardize the format of the entries in the CHANGELOG, express all of them as imperative commands, as opposed to past-tense or in the third-person.
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
ivanperez-keera
added a commit
that referenced
this issue
Apr 26, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The changelogs currently list the path associated to a change, prior to the summary of the change. For example, Yampa's CHANGELOG recently lists:
Yampa/yampa/CHANGELOG
Lines 1 to 6 in 8461217
The addition of paths to those changes adds very little useful information (if any at all). The decision of how big a part of the path to show in the CHANGELOG (e.g., src/FRP/Yampa.hs vs src/) is quite arbitrary. Adding the paths also implies that, sometimes, a change may have to be listed multiple times, since it affected multiple paths, and the re-wrapping of change summaries to fit in one line makes for awkward diffs and makes reading the changelogs harder.
For an example of a CHANGELOG with no paths, see:
https://github.com/ivanperez-keera/dunai/blob/1755154b3e6970633db961cf28262ffdd127aa63/dunai/CHANGELOG#L1-L11
I propose to remove those paths from the CHANGELOGs (in both
yampa
andyampa-test
) and decrease the indentation to two spaces. The change in formatting should also be applied to past entries in the CHANGELOGs.The text was updated successfully, but these errors were encountered: