[PATCH] bfd/version.h: Add rationale for BFD_VERSION_DATE (Re: meaning of "Automatic date update in version.in" commits)

Hi,

On 09/22/2017 12:59 AM, Alan Modra wrote:
> On Thu, Sep 21, 2017 at 08:38:57PM +0300, Petr Ovtchenkov wrote:
>> 1. Explicit "Automatic date update in version.in" commits litter commits tree,
>> but useless. All required info already present in git.
>> [Thanks for Ian Lance Taylor for the background!]
> 
> It isn't useless.  People build binutils from a variety of sources,
> git, tarballs, distro sources, then report bugs.  We want something
> that can easily identify the source they used.  The bfd version plus
> date is usually good enough for that purpose.
> 
>> Let's remove this "Automatic date update in version.in" commits.
> 
> No.  That won't happen unless we have something equivalent.  And it
> must work *without* git.
> 
>> 2. I see a lot of suggestions "Let's push date to SONAME, the date we
>> will take from ....".
>>
>> I trying to prevent such "solutions". Because it's not a solution, but
>> origin of another problems.
> 
> The date is in the soname because people naturally expect shared
> libraries with the same soname to have compatible ABIs.  During
> development, we could bump the bfd version on every ABI change, but
> that's just another thing contributors and maintainers would need to
> remember.  It's much easier for all if the soname contains the date.
> Again, it's not perfect but is good enough.
> 
> None of this is going to change just because you don't like a date
> stamp in the source.  You do realize that a bisect uses a binary
> search, don't you?  So doubling the number of commits just needs one
> extra build/test step on average.
> 
> Yes, it would be nice if the automatic date stamp update didn't happen
> when the most recent commit was a date update..
> 

I like this summary.  How about we put something like that in bfd/version.h ?

I assume that the bot is just replacing the line with
BFD_VERSION_DATE instead of regenerating the whole file from
scratch, but that's just guessing.  (I don't have sourceware
shell access; I have no idea how the auto updater is implemented.)

------------
From 08c8f26323a978608256cd574321d9f39658cc51 Mon Sep 17 00:00:00 2001
From: Pedro Alves <[email protected]>
Date: Fri, 22 Sep 2017 10:17:03 +0100
Subject: [PATCH] bfd/version.h: Add rationale for BFD_VERSION_DATE

bfd/ChangeLog:
yyyy-mm-dd  Pedro Alves  <[email protected]>
	    Alan Modra  <[email protected]>

	* version.h: Add comment.
---
 bfd/version.h | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/bfd/version.h b/bfd/version.h
index 955269f..7d9151a 100644
--- a/bfd/version.h
+++ b/bfd/version.h
@@ -1,3 +1,21 @@
+/* The date below is automatically updated every day by a bot.  During
+   development, we include the date in the tools' version strings
+   (visible in 'ld -v' etc.) because people build binutils from a
+   variety of sources - git, tarballs, distro sources - and we want
+   something that can easily identify the source they used when they
+   report bugs.  The bfd version plus date is usually good enough for
+   that purpose.
+
+   During development, this date ends up in libbfd and libopcodes
+   sonames because people naturally expect shared libraries with the
+   same soname to have compatible ABIs.  We could bump the bfd version
+   on every ABI change, but that's just another thing contributors and
+   maintainers would need to remember.  Instead, it's much easier for
+   all if the soname contains the date.  This is not perfect but is
+   good enough.
+
+   In releases, the date is not included in either version strings or
+   sonames.  */
 #define BFD_VERSION_DATE 20170920
 #define BFD_VERSION @bfd_version@
 #define BFD_VERSION_STRING  @bfd_version_package@ @bfd_version_string@
-- 
2.5.5