Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Improve readability of CHANGELOGs #261

Closed
ivanperez-keera opened this issue Apr 20, 2023 · 0 comments
Closed

Improve readability of CHANGELOGs #261

ivanperez-keera opened this issue Apr 20, 2023 · 0 comments
Assignees
@ivanperez-keera
Labels
enhancement
Milestone
Yampa 0.14.3

Comments

@ivanperez-keera
Copy link
Owner

ivanperez-keera commented Apr 20, 2023 •
edited
Loading

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

2023-04-07 Ivan Perez <ivan.perez@keera.co.uk>
* Yampa.cabal: Version bump (0.14.2) (#259).
* src/: Conformance with style guide (#255).
* examples/: Conformance with style guide (#255), move example to
yampa-test library (#257).
* README: Add game to list of games and apps in README (#254).

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 and yampa-test) and decrease the indentation to two spaces. The change in formatting should also be applied to past entries in the CHANGELOGs.
@ivanperez-keera ivanperez-keera added this to the Yampa 0.(14+X).(2+Y) milestone Apr 26, 2023
@ivanperez-keera ivanperez-keera self-assigned this Apr 26, 2023
ivanperez-keera added a commit that referenced this issue Apr 26, 2023
@ivanperez-keera
yampa: Re-format CHANGELOG to remove paths. Refs #261.
4877a12 
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
@ivanperez-keera
yampa: List version bumps as top group entry in CHANGELOG. Refs #261.
d7362db 
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
@ivanperez-keera
yampa: Reformat issue references in CHANGELOG. Refs #261.
ec95005 
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
@ivanperez-keera
yampa: Remove vertical space in CHANGELOG. Refs #261.
620cf9d 
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
@ivanperez-keera
yampa: Reduce indentation to 4 spaces. Refs #261.
e72f2fa 
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
@ivanperez-keera
yampa: Fix typo in CHANGELOG entry. Refs #261.
ae766aa 
To aid in reading the file, fix existing typo.
ivanperez-keera added a commit that referenced this issue Apr 26, 2023
@ivanperez-keera
yampa: Express CHANGELOG entries as imperative commands. Refs #261.
9d20f01 
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
yampa-test: Re-format CHANGELOG to remove paths. Refs #261.
7f03e8a 
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
@ivanperez-keera
yampa-test: Reduce indentation to 4 spaces. Refs #261.
05d2abb 
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
@ivanperez-keera
yampa-test: Express CHANGELOG entries as imperative commands. Refs #261.
36949c7 
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
yampa: Document changes in CHANGELOG. Refs #261.
a71516e
ivanperez-keera added a commit that referenced this issue Apr 26, 2023
@ivanperez-keera
yampa-test: Document changes in CHANGELOG. Refs #261.
e76f3e2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ivanperez-keera ivanperez-keera

Labels
enhancement
Projects
None yet
Milestone
Yampa 0.14.3
Development

No branches or pull requests
1 participant
@ivanperez-keera