| 1 |
>>>>> On Wed, 17 Sep 2014, Michał Górny wrote: |
| 2 |
|
| 3 |
> Dnia 2014-09-16, o godz. 10:18:35 |
| 4 |
> hasufell <hasufell@g.o> napisał(a): |
| 5 |
|
| 6 |
>> Ulrich Mueller: |
| 7 |
>> > |
| 8 |
>> > ChangeLogs are aimed at users |
| 9 |
>> |
| 10 |
>> Did any1 ask them if they care? |
| 11 |
|
| 12 |
> A bit off-topic but asking such a question usually makes some |
| 13 |
> developers point out that they are users too and they do care :). |
| 14 |
|
| 15 |
> However, in this particular context it could be helpful to do some |
| 16 |
> research. As people have pointed out, users may actually prefer using |
| 17 |
> some git web-interface or git clone to get the details. |
| 18 |
|
| 19 |
It is two questions that need to be answered. The first question is if |
| 20 |
we want to keep a ChangeLog that is separate from commit messages. The |
| 21 |
second question (and it can only be answered after the first one) is |
| 22 |
how the information should be transmitted to users. It doesn't make |
| 23 |
sense to mix the two questions, or to answer the second one before the |
| 24 |
first. |
| 25 |
|
| 26 |
The original intention back in 2002 was having a ChangeLog containing |
| 27 |
information somewhat complementary to commit messages. This can still |
| 28 |
be found in skel.ChangeLog: |
| 29 |
|
| 30 |
| This changelog is targeted to users. This means that the comments |
| 31 |
| should be well explained and written in clean English. |
| 32 |
|
| 33 |
And: |
| 34 |
|
| 35 |
| Any details about what exactly changed in the code should be added |
| 36 |
| as a message when the changes are committed to cvs, not in this |
| 37 |
| file. |
| 38 |
|
| 39 |
That different messages can be used was acknowledged in the November |
| 40 |
2011 council meeting (and yours truly had voted in favour of it): |
| 41 |
|
| 42 |
| The Council agreed that developers are free to use different |
| 43 |
| messages for ChangeLog and commit, but they are responsible for the |
| 44 |
| messages, and the Council still expects appropriate messages to be |
| 45 |
| used. |
| 46 |
|
| 47 |
So the research that needs to be done first is to find out how often |
| 48 |
our ChangeLog entries differ from the commit log. If it turns out that |
| 49 |
they are identical in 99 % of all cases, then it obviously makes no |
| 50 |
sense to maintain the same information in two places, and ChangeLogs |
| 51 |
should be abandoned. (For my own commits, I would estimate that |
| 52 |
messages are different for 20 % of commits.) |
| 53 |
|
| 54 |
Only when this has been answered, we should discuss how the |
| 55 |
information should be formatted and how users should obtain it. |
| 56 |
Some ideas: |
| 57 |
- We could have an echangelog replacement (integrated into repoman?) |
| 58 |
for nice formatting of commit messages. |
| 59 |
- If we abandon separately maintained ChangeLog files, then there |
| 60 |
should be some means for correcting mistakes in commit messages. |
| 61 |
Maybe "git notes" could be used? |
| 62 |
- There is certainly room for improvement how to communicate news |
| 63 |
about a package to users, apart from elog messages and GLEP 42 news |
| 64 |
items. Maybe readme.gentoo.eclass could be extended to optionally |
| 65 |
install a NEWS.gentoo file along with README.gentoo? |
| 66 |
|
| 67 |
Ulrich |
Archives