On Mon, Dec 4, 2017 at 1:45 PM, Stefan Sperling <stsp_at_apache.org> wrote:
> On Mon, Dec 04, 2017 at 12:16:37PM +0100, Johan Corveleyn wrote:
>> Examples:
>> [U:major] Better interactive conflict resolution for tree conflicts
>> [U:minor] ra_serf: Adjustments for serf versions with HTTP/2 support
>> [U:client] Fix 'svn diff URL_at_REV WC' wrongly looks up URL_at_HEAD (issue #4597)
>> [U:client-server] Fix bug with canonicalizing Window-specific
>> drive-relative URL
>> [D:api] New svn_ra_list() API function
>> [D:bindings] JavaHL: Allow access to constructors of a couple JavaHL classes
>
>> To get a rough idea: since we don't have any commit messages
>> containing such lines in our history, I've added a --pocfirstlines
>> option, which just takes the first line of every log message (ignoring
>> lines with 'STATUS', 'CHANGES', 'bump', or starting with '*'), putting
>> them in the "User -> General" section.
>
> If we're gonna add some form of structured information to our log messages,
> I'd prefer the git model with a simple heuristic which builds an uncategorized
> list:
>
> The first line of the message is what will end up in CHANGES. If the line
> mentions an issue number, that will appear in CHANGES as (issue #N), else
> the revision number will appear in changes as (rN). If the line matches
> '[Rr]evert rN' then a prior entry for rN is removed again. If the log message
> matches '[Ff]ollow(ing)-up to' the entry is dropped. If the log message
> contains '[Nn]o functional change' anywhere, the entry is dropped.
That implies that every commit has something useful to add to CHANGES
(except reverts, followups and non-functional changes). That's not the
case. In my proposal the changelog annotation is entirely optional.
Committers need to think whether their commit merits a changelog entry
(and the phrasing of the changelog entry can be different from the
first line of the commit message, which is more aimed at fellow
developers trying to understand a particular commit / how / why /
...).
> That should suffice for the most tedious part of the task: Getting a list
> of eligible entries. Categorizing the resulting list can be done by hand,
> and remaining unimportant changes must be removed by hand.
>
> I would refrain from trying to over-automate this task. It's not a lot of work
> compared to the time we spend writing code. I think I have added most of the
> 1.10 entries in CHANGES myself just by reading through the log, and even that
> wasn't too much effort. It took about a day and a half, and it also forced me
> to read through the entries in detail which helped understand the impact of
> each change. This was a much bigger problem from the project's origins through
> to 1.8, when we had a lot of active developers. For 1.9/1.10 we had a lot less
> activity overall and we can expect it to decrease further in the future.
>
> Even if we tag log messages as you suggest, we'll need some mechanism to
> deal with tags which are wrong or missing, and that's also tedious and
> requires checking each entry anyway. Also, it is unclear how tagging as
> suggested helps with features developed on trunk over long periods of time.
> For example, the conflict resolver probably got a couple hundred commits
> but it only requires one CHANGES entry. Should these all be tagged 'U:major'?
No, none of those individual commits requires a changelog entry. I'd
say for big new features it makes little sense to add tags for
incremental steps in functionality. Though entries such as "Add
interactive tree conflict resolver", "TC resolver: handle incoming
move vs. local edit", etc... (I'm just making these up) might be
useful.
> Or do we now enforce branch-based development so that only the final merge
> commit is tagged, with the downsides that implies, such as no testing during
> development by anyone except the original developer?
No, I'm not suggesting that.
> Or do we add feature tags
> which our script can recognize, such as [U:conflict-resolver]? Could we now
> end up needing multiple tags for some messages? Will it become too complicated?
No specific feature tags I'd say (but "sections", for the existing
sections in CHANGES). Multiple changelog entries in one commit message
would be allowed, but it'd be rather exceptional (for instance, if one
commit adds something User-visible and Developer-visible at the same
time, or a new feature and a corresponding "API change" -- i.e. you
want a changelog entry in both sections).
> I believe that whatever we do, somebody will still have to read the full log
> and check each entry in CHANGES to avoid listing a lot of trivial stuff,
> and to make sure the most impactful changes appear at the top.
I don't think so. Not if the changelog annotations are used well (as
with writing log message in general, this probably requires practice
to get right -- it'd be a part of reviewing each other's changes to
potentially give feedback on the (optional) changelog annotation).
The intention is that the RM doesn't need to go through all the full
log messages in detail, but that he can trust the output of
write-changelog, combined with trust in the quality of the log
messages involved. Basically CHANGES is built up incrementally as we
go in the commit messages themselves (and reviewed as part of our
normal workflow while the work is being done and everything is fresh
in everyone's memory).
Of course, the RM might see in the output of write-changelog that some
entries can be combined or summarized further, rephrased or reordered.
That's fine (in some cases he might want to correct the changelog
annotation in the underlying log message). But he shouldn't have to go
read all the details, unless something's wrong.
--
Johan
Received on 2017-12-04 14:18:25 CET