Bug#549910: debian-policy: Specify requirement in terms of upgradeability, interface stability

[Raphaël Hertzog]

Package: debian-policy
Version: 3.8.3.0
Severity: wishlist

We have some unwritten packaging rules and it would be good to write them
down even if some of them appear to be obvious to most of us. I think in
particular to stuff like:

- a package must at least be upgradable from one stable release to the next:
  - transitional packages are required when the software is renamed
  - {pre,post}{inst,rm} snippets dealing with upgrade issues must be kept
    for at least one release (but it's better to keep them for 2-3
    releases)

- a package must provide some interface stability (names of programs,
  ABI/API of libraries, location of data files, etc.) when other packages
  depend on it. In that case,  any change must be coordinated and
  appropriate dependencies must be added. It should give examples of
  Breaks:, bumped Depends when an change is made in a non-backwards
  compatible way, temporary compatibility symlinks, etc.

We have enough cases like this that it would be good to be able to point
to a policy chapter dealing with such requiremnts when we file bug
reports. Also it's important information that newbie packagers should be
able to learn somewhere, and I think policy is the most appropriate
place. It's not only best-practice, it's a must have.

-- System Information:
Debian Release: squeeze/sid
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (150, 'experimental')
Architecture: i386 (x86_64)

Kernel: Linux 2.6.30-2-amd64 (SMP w/2 CPU cores)
Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base                      0.9.4      utilities to manage online documen

-- no debconf information



--
To UNSUBSCRIBE, email to debian-bugs-dist-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Manoj Srivastava]

On Tue, Oct 06 2009, Raphaël Hertzog wrote:

> Package: debian-policy
> Version: 3.8.3.0
> Severity: wishlist
>
> We have some unwritten packaging rules and it would be good to write them
> down even if some of them appear to be obvious to most of us. I think in
> particular to stuff like:
>
> - a package must at least be upgradable from one stable release to the next:
>   - transitional packages are required when the software is renamed
>   - {pre,post}{inst,rm} snippets dealing with upgrade issues must be kept
>     for at least one release (but it's better to keep them for 2-3
>     releases)
>
> - a package must provide some interface stability (names of programs,
>   ABI/API of libraries, location of data files, etc.) when other packages
>   depend on it. In that case,  any change must be coordinated and
>   appropriate dependencies must be added. It should give examples of
>   Breaks:, bumped Depends when an change is made in a non-backwards
>   compatible way, temporary compatibility symlinks, etc.
>
> We have enough cases like this that it would be good to be able to point
> to a policy chapter dealing with such requiremnts when we file bug
> reports. Also it's important information that newbie packagers should be

        Seems like not providing upgrade paths is already a bug, as is
 breaking unrelated software by changing  interfaces without warning.
 Do we really need to have policy to tell people not to create buggy
 packages? Policy is not, after all, a club to beat people on the head
 with.

        Ideally, policy should be minimalistic, and only contain things
 where
  a) there are standard interfaces that packagers may depend on
     (./debian/control, for example)
  b) There are multiple technically viable solutions (web doc root is
     /var/www), and one must select one for interoperability.

        The size and density of the policy manuals are always an issue,
 and it seems to me that these are obvious bugs that are already covered
 by release manager requirements and bug reporting guidelines; adding
 these to policy would be redundant.

        manoj
--
Bachelor: A guy who is footloose and fiancee-free.
Manoj Srivastava <srivasta@...> <http://www.debian.org/~srivasta/>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


--
To UNSUBSCRIBE, email to debian-policy-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Raphaël Hertzog]

On Tue, 06 Oct 2009, Manoj Srivastava wrote:
>  Do we really need to have policy to tell people not to create buggy
>  packages?

Well, there are people out there that don't know that doing such things
are bugs. I would like to be able to educate them pointing to our policy,
explaining that it's what makes of us a quality distribution.

> Policy is not, after all, a club to beat people on the head
> with.

It is however a required reading for any new maintainer.

>         The size and density of the policy manuals are always an issue,
>  and it seems to me that these are obvious bugs that are already covered
>  by release manager requirements and bug reporting guidelines; adding

Where ?

Cheers,
--
Raphaël Hertzog


--
To UNSUBSCRIBE, email to debian-policy-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Giacomo A. Catenazzi]

Raphaël Hertzog wrote:

> Package: debian-policy
> Version: 3.8.3.0
> Severity: wishlist
>
> We have some unwritten packaging rules and it would be good to write them
> down even if some of them appear to be obvious to most of us. I think in
> particular to stuff like:
>
> - a package must at least be upgradable from one stable release to the next:
>   - transitional packages are required when the software is renamed
>   - {pre,post}{inst,rm} snippets dealing with upgrade issues must be kept
>     for at least one release (but it's better to keep them for 2-3
>     releases)

I agree

>
> - a package must provide some interface stability (names of programs,
>   ABI/API of libraries, location of data files, etc.) when other packages
>   depend on it. In that case,  any change must be coordinated and
>   appropriate dependencies must be added. It should give examples of
>   Breaks:, bumped Depends when an change is made in a non-backwards
>   compatible way, temporary compatibility symlinks, etc.

I find difficult to implement it in policy in a clear way. We already have
nearly the same requirement for ABI/API in libraries: the package name must
contain the SOVERSION.
If we add such requirement, I would change chapter 8 from
"Shared libraries" into "Shared libraries and common files" and adding
a general stability suggestion.

BTW I find no reference in policy about the NEWS.Debian file. It would
nice to require to document (at last for one stable release) all (also
user visibe API/ABI) incompatibilities in such files.

ciao
        cate



--
To UNSUBSCRIBE, email to debian-bugs-dist-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Manoj Srivastava]

On Wed, Oct 07 2009, Raphael Hertzog wrote:

> On Tue, 06 Oct 2009, Manoj Srivastava wrote:
>>  Do we really need to have policy to tell people not to create buggy
>>  packages?
>
> Well, there are people out there that don't know that doing such things
> are bugs. I would like to be able to ede them pointing to our policy,
> explaining that it's what makes of us a quality distribution.

        This by itself does not meet the criteria for inclusion in
 policy. There are all kinds of things that are bugs, and are not
 mentioned in policy; and adding them to policy is needless bloat. If
 you wish, a new document can be started somewhere, about common
 mistakes, and  this can fit well in there.


>> Policy is not, after all, a club to beat people on the head
>> with.
>
> It is however a required reading for any new maintainer.

        Again, that is  a reason to  keep the policy document from bring
 bloated, and prevent mission creep.

>>         The size and density of the policy manuals are always an issue,
>>  and it seems to me that these are obvious bugs that are already covered
>>  by release manager requirements and bug reporting guidelines; adding
>
> Where ?

 Well, for the latter:
 http://www.debian.org/Bugs/Developer
  Since changes in interfaces will make unrelated software break,

        For the former, I think it would be a decent addition to a
 document like
 a) http://release.debian.org/lenny/rc_policy.txt
 or, failing that, the developers reference as a "Good Practice".

        I just don't see this as a policy matter.

        manoj
--
Some people only open up to tell you that they're closed.
Manoj Srivastava <srivasta@...> <http://www.debian.org/~srivasta/>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


--
To UNSUBSCRIBE, email to debian-policy-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Manoj Srivastava]

On Wed, Oct 07 2009, Giacomo A. Catenazzi wrote:

> BTW I find no reference in policy about the NEWS.Debian file. It would
> nice to require to document (at last for one stable release) all (also
> user visibe API/ABI) incompatibilities in such files.

        It is a goos practice, yes. Seems to me that that indicates it
 belongs to the developers reference?

        manoj
--
Behold the warranty -- the bold print giveth and the fine print taketh
away.
Manoj Srivastava <srivasta@...> <http://www.debian.org/~srivasta/>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


--
To UNSUBSCRIBE, email to debian-policy-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Giacomo A. Catenazzi]

Manoj Srivastava wrote:
> On Wed, Oct 07 2009, Giacomo A. Catenazzi wrote:
>
>> BTW I find no reference in policy about the NEWS.Debian file. It would
>> nice to require to document (at last for one stable release) all (also
>> user visibe API/ABI) incompatibilities in such files.
>
>         It is a goos practice, yes. Seems to me that that indicates it
>  belongs to the developers reference?

It is also an API (dpkg-listchanges uses it) and IIRC in last year (or maybe
two year ago) the format was standardized (i.e. the same format as
debian/changelog).

Anyway I would propose the inclusion of NEWS.Debian on policy only
after policy will reference it.

ciao
        cate




--
To UNSUBSCRIBE, email to debian-policy-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Russ Allbery-2]

Raphaël Hertzog <hertzog@...> writes:

> We have some unwritten packaging rules and it would be good to write
> them down even if some of them appear to be obvious to most of us. I
> think in particular to stuff like:

> - a package must at least be upgradable from one stable release to the next:
>   - transitional packages are required when the software is renamed
>   - {pre,post}{inst,rm} snippets dealing with upgrade issues must be kept
>     for at least one release (but it's better to keep them for 2-3
>     releases)

Documenting this seems like a good idea to me as well, although I'm not so
sure about the transitional package bit.  Isn't that to some extent
dependent on what sort of a transition it is and the details of just how
the change is being done, including how backward-compatible the new
version is?

I do really like the idea of documenting that we support upgrades from
the previous stable, but not more than that, in Policy.  That feels like
solid Policy material to me, and I don't think we say that explicitly at
the moment.

> - a package must provide some interface stability (names of programs,
>   ABI/API of libraries, location of data files, etc.) when other packages
>   depend on it. In that case,  any change must be coordinated and
>   appropriate dependencies must be added. It should give examples of
>   Breaks:, bumped Depends when an change is made in a non-backwards
>   compatible way, temporary compatibility symlinks, etc.

This feels very fuzzy to me.  I wonder if it would do better in devref for
a while and then we can see if a Policy-level core emerges that could be
lifted into Policy.

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



--
To UNSUBSCRIBE, email to debian-bugs-dist-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...

[Russ Allbery-2]

Manoj Srivastava <srivasta@...> writes:
> On Wed, Oct 07 2009, Giacomo A. Catenazzi wrote:

>> BTW I find no reference in policy about the NEWS.Debian file. It would
>> nice to require to document (at last for one stable release) all (also
>> user visibe API/ABI) incompatibilities in such files.

>         It is a goos practice, yes. Seems to me that that indicates it
>  belongs to the developers reference?

Since NEWS.Debian is a file with a defined syntax that's parsed by other
programs, I think Policy would be an appropriate place to document the
syntax and intended use.  Specific details on when it is or isn't
appropriate to put something in that file is probably more a devref thing.

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


--
To UNSUBSCRIBE, email to debian-policy-REQUEST@...
with a subject of "unsubscribe". Trouble? Contact listmaster@...