Russ Allbery wrote: > Okay, once more for the win.
Hoorah! :) I don't see any problems in the normative content, so I'd second this if I could. Cosmetic nits (patch below): [...] > +++ b/policy.sgml [...] > @@ -5633,17 +5634,29 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) [...] > <p> > + To determine the <var>soversion</var>, look at > + the <tt>SONAME</tt> of the library, stored in the > + ELF <tt>SONAME</tt> attribute. it is usually of the ^^ Capitalization: s/it/It/ [...] > + A common example of when a change to the is required is a ^^^^^^^^^ Missing word: s/to the/to the dependency version/. (In a previous version of the patch, this passage was discussing symbols files only and said <var>minimal-version</var>.) [...] > + no symbol version. <var>minimal-version</var> is the most > + recent version of the shared library that changed the > + behavior of that symbol, whether by adding it, changing its ~~~~~~ ~~~~~~~~ > + function signature (the parameters, their types, or the > + return type), or its behavior in a way that is visible to a ~~~~~~~~~~~~~~~ > + caller. <var>id-of-dependency-template</var> is an optional Maintaining parallel construction: s/its behavior/changing its behavior/. [...] > + In our example, if the last change to the <tt>zlib1g</tt> > + package that could change behavior for a client of that > + library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then > + the <tt>shlibs</tt> entry for this library could say: > + <example compact="compact"> > + libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1) > + </example> Should this say (>= 1:1.2.3.3.dfsg-1~) or (>= 1:1.2.3.3.dfsg) to be kind to backporters? Before the patch, the example said ">= 1:1.1.3". -- >8 -- Subject: symbols/shlibs policy: cosmetic fixes Use "zlib1g (>= 1:1.2.3.3.dfsg-2~)" in the sample shlibs dependency field to emphasize the backport-friendly convention described in the sharedlibs-updates section. Also correct two small typos --- one sentence is uncapitalized and another missing a noun --- and rephrase a sentence that describes when to bump the dependency-version to make it easier to read. --- diff --git a/policy.sgml b/policy.sgml index fa1c39a..050c688 100644 --- a/policy.sgml +++ b/policy.sgml @@ -5646,7 +5646,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) <p> To determine the <var>soversion</var>, look at the <tt>SONAME</tt> of the library, stored in the - ELF <tt>SONAME</tt> attribute. it is usually of the + ELF <tt>SONAME</tt> attribute. It is usually of the form <tt><var>name</var>.so.<var>major-version</var></tt> (for example, <tt>libz.so.1</tt>). The version part is the part which comes after <tt>.so.</tt>, so in that example it @@ -6238,9 +6238,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) </p> <p> - A common example of when a change to the is required is a - function that takes an enum or struct argument that controls - what the function does. For example: + A common example of when a change to the dependency version + is required is a function that takes an enum or struct + argument that controls what the function does. For example: <example> enum library_op { OP_FOO, OP_BAR }; int library_do_operation(enum library_op); @@ -6489,8 +6489,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) recent version of the shared library that changed the behavior of that symbol, whether by adding it, changing its function signature (the parameters, their types, or the - return type), or its behavior in a way that is visible to a - caller. <var>id-of-dependency-template</var> is an optional + return type), or changing its behavior in a way that is + visible to a caller. + <var>id-of-dependency-template</var> is an optional field that references an <var>alternative-dependency-template</var>; see below for a full description. @@ -6795,10 +6796,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) <p> In our example, if the last change to the <tt>zlib1g</tt> package that could change behavior for a client of that - library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then + library was in version <tt>1:1.2.3.3.dfsg-2</tt>, then the <tt>shlibs</tt> entry for this library could say: <example compact="compact"> - libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1) + libz 1 zlib1g (>= 1:1.2.3.3.dfsg-2~) </example> This version restriction must be new enough that any binary built against the current version of the library will work @@ -6810,7 +6811,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) As zlib1g also provides a udeb containing the shared library, there would also be a second line: <example compact="compact"> - udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1) + udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-2~) </example> </p> </sect2> -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20120812231526.GA4227@mannheim-rule.local