On 02-02-18 22:59, Lubomir I. Ivanov wrote:
hello,
1)
this suggestion is triggered by the need for streamlining the addition
of changelog entries by contributors in the CHANGELOG.md file.
right now, we merge PRs that make an important change, but such PRs do
not append a change in the CHANGELOG.md file. adding notes in
CHANGELOG.md has to be made a requirement in PRs, otherwise before a
release one has to go over the usually big list of commits and find
relevant missing entries.
Historically, we have pretty concise changelogs, more or less hand made,
and relatively high level. Like "Numerous spelling errors", "Lots of
small UI fixes". Obviously, this does tell only a part of the story, and
possible relevant change can be forgotten in this process. So this does
not seem the way to go.
However, the big question is here: for who do we write the changelog?
When it is for the website and announcements on internet, I tend to
prefer the short and concise high level like we had, instead of a long
list that seems correct and detailed enough (for who?).
For example: in the PR 1091 one item is "Cloud-storage: support
non-https:// repositories for saving" ... yes I know where this is
coming from ... but the general public?
by doing that we also need a standardized CHANGELOG.md entry format.
my suggestion is the following:
- Area: change that was made (#github-link)
examples:
- Planner: fixed a bug when moving data points (#32132)
- Mobile: fixed a bug when clicking button X. The bug also affected
menu X (#32132)
notes about the format:
- the area name is uppercase
- lowecase after the "Area: ", should it be uppercase here?
- no period at the end of an entry only in-between sentences
- when there is a related issue a (#github-link) has to be added at the end
- first line stats with "- " and no indentation. the next lines are
indented by " ".
example areas:
- Planner
- Mobile
- Desktop
- Bluetooth
- Map-widget
- Cloud-storage
- Uemis
- Import
- Export
- Profile
- Libdivecomputer
opinions about this?
Nice, but a little too detailed to my liking. Are you thinking of some
automation/tooling behind it to check for these rules?
2)
for commit messages- until now we have accepted commit messages that
do not specify an area, like these:
Fix bug when clicking button X
Small whitespace fix
Fine for me. When I want to look at a commit, I do not only read the
title, but also the rest of the text and even the code change if needed.
In practice, it is often difficult to exactly pinpoint the area (and
being concise). For example (from the PR 1091), "Bluetooth: do not add
duplicate BT/BLE items", this mobile only, and it is even not
(technically) restricted to Bluetooth. And the originating commit says
"connectionList" and the related issue #1069 even says "mobile: During
DC import, Rescan duplicates connections".
these are kind of vague, thus i would suggest requiring (perhaps not
strictly) an area prefix or a filename, like so:
Divelist: Fix bug when clicking button X
divelist.cpp: fix whitespace
any opinions about this too?
In general: ok. But I come back to my earlier remark: for who do we
write the changelog?
--jan
_______________________________________________
subsurface mailing list
[email protected]
http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface
