Re: document symbols

[Russ Allbery <rra@debian.org>]

Jonathan Nieder <jrnieder@gmail.com> writes:
> Russ Allbery wrote:

>> I'm therefore including here the complete SGML source of that section
>> not in diff format, followed by the diff of everything *outside* of
>> that section.  I think this will be easier to review.

> Thanks!  I would have preferred a diff since it shows the text that is
> being replaced, too, but let's go with this for a first pass.

Yeah, it's frustrating to review something this large, and none of the
normal tools do a particularly good job at it.  A side-by-side contextual
diff tool is probably best.

Anyway, thank you for the detailed review, and apologies for taking so
long to get back to this.  The amount of work required is intimidating,
and I kept putting it off.

For the most part, I adopted your changes; assume that if I don't comment
here specifically, I've incorporated that change.  (I started by applying
your interdiff and then only changing the bits that I thought I could
further clarify.)

> [...]
>> 	<p>
>> 	  If a package contains a binary or library which links to a
>> 	  shared library, we must ensure that, when the package is
>> 	  installed on the system, all of the libraries needed are also
>> 	  installed.

> This text is carried over from before and contains a requirement I never
> noticed before.  Suppose my package contains two binaries:  maintool and
> side-tool.  The latter is not very important and links to libbiglibrary.
> I might be tempted to make the dependency by my package on libbiglibrary
> a Recommends instead of a Depends.  The above says I must not.

> Intentional?  It seems like good policy, anyway.

Could you open a separate bug about this?  I think we should allow
Recommends, but as you say it's already in the current wording and this
change is already too complicated.  We should discuss it separately.

> This means packages must not hard-code library dependencies.  It also
> seems like good policy, but I suspect it would render packages such as
> chromium that use dlopen() and hard-code the corresponding library name
> in dependencies RC-buggy.

Your fix (making dependencies for dlopen a should instead of a must)
looked like a good way of fixing this problem to me.  Thanks!

>> 	  To allow these dependencies to be constructed, shared libraries
>> 	  must provide either a <file>symbols</file> file or
>> 	  a <file>shlibs</file> file, which provide information on the
>> 	  package dependencies required to ensure the presence of this
>> 	  library.

> Subject/verb agreement: s/provide/provides/

While that's technically correct, it looks completely wrong to me.  I
reworded to make this two sentences instead, so that it's both formally
correct and "feels" right.

> If I remove a symbol that was documented to be private or change the
> behavior of a function when given invalid arguments, is that a
> backward-compatible change?

> If I add change the implementation in such a way that the library
> becomes so large that some large programs cannot use it any more, is
> that a backward-incompatible change?

You addressed this by introducing the concept of a "reasonable" program
but not defining it.  That sounded like the right approach to me, but I
felt the need to say more, so I added a footnote explaining the intent:

    There are two types of ABI changes: ones that are
    backward-compatible and ones that are not.  An ABI change is
    backward-compatible if any reasonable program or library that
    was linked with the previous version of the shared library
    will still work correctly with the new version of the shared
    library.<footnote>
      An example of an "unreasonable" program is one that uses library
      interfaces that are documented as internal and unsupported.  If the
      only programs or libraries affected by a change are "unreasonable"
      ones, other techniques, such as declaring <tt>Breaks</tt>
      relationships with affected packages or treating their usage of the
      library as bugs in those packages, may be appropriate instead of
      changing the SONAME.  However, the default approach is to change the
      SONAME for any change to the ABI that could break a program.
    </footnote>

> Unrelated change.  The patch would have been easier to review if this
> were a separate commit, which could have gone straight to master since
> it doesn't change the output.

Yes, sorry.  I really hate the whole diff system for making changes to
text documents, since I always reformat text documents as I work on them.
I'll try to avoid this when people find it confusing, but as long as I'm
writing the patches, you may have to just live with some of this, since
putting more barriers in the way of writing text for Policy will mean that
I'll do even less work than I do now.  :/  That said, I agree that it's
kind of annoying for review, and I'll try to get better about not doing
it.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>