svn commit: r350505 - in head: contrib/binutils/binutils/doc gnu/usr.bin/binutils/objdump

[John Baldwin]

On 8/1/19 11:09 AM, Ian Lepore wrote:
> On Thu, 2019-08-01 at 10:39 -0700, John Baldwin wrote:
>> On 7/31/19 8:13 PM, Ed Maste wrote:
>>> On Thu, 1 Aug 2019 at 12:51, Rodney W. Grimes <
>>> freebsd at gndrsh.dnsmgr.net> wrote:
>>>>
>>>> That would be fine, the important thing is that the
>>>> r350505 gets listed in the file,
>>>
>>> I don't see any reason that r350505 specifically should be in a
>>> release note - this is a minor clarification of an existing
>>> deprecation notice. It seems having an overall "deprecation
>>> notices"
>>> section in the release notes would make sense, but they should
>>> really
>>> persist from version to version. Should we add a top-level
>>> DEPRECATION_NOTICES file perhaps? Or tag deprecation notices with
>>> some
>>> sort of comment in the source so they can be found with a 'grep'
>>> during release preparation?
>>
>> I think it would make sense to have "sections" in RELNOTES that mimic
>> the sections we have in the existing release notes (e.g. kernel vs
>> userland).  That is effectively what GDB does with a top level NEWS
>> file.  This approach would hopefully make it easier to translate this
>> file into the real release notes.  It also means that a given "note"
>> can evolve over time (e.g. it might start with "XYZ is deprecated" to
>> "XYZ is removed" if a deprecation note is added and merged and later
>> it
>> is removed) rather than only having a running journal ala UPDATING.
>>
>> On the question of whether we want a dedicated section just for
>> deprecation notices, I'm not sure.  Probably we can just stick with
>> the
>> layout of our existing release notes?
>>
> 
> I wonder why it is that this relnotes file is some kind of major
> attractor for complexity?
> 
> As I understand it, the *entire* intent of this file was "if you forget
> to add Relnotes: yes" to a commit, this gives you a way to flag the
> commit after the fact, since commit messages are immutable.
> 
> If people realize they forgot Relnotes: yes, and the remedy for that is
> that they have to spelunk around in some complex formatted file to find
> the "right section" (whatever that means)... well, I think in the real
> world: they won't.

My assumption was that relnotes would remain a simple text file.  I think
the win is that you aren't editing XML or SGML or the like, and that you
can go back and edit existing entries if needed as well as document
something when you missed relnotes: yes.  The more work we put into having
something closer to the finished product in this file, the less work re@
has to do to parse commit messages.

-- 
John Baldwin