[PATCH] docs: Document backport criteria

[Daniel Axtens]

Stephen Finucane <stephen at that.guru> writes:

> On Wed, 2019-05-15 at 03:00 +1000, Daniel Axtens wrote:
>> Stephen Finucane <stephen at that.guru> writes:
>> 
>> > Explain why we don't want to be in the business of backport certain
>> > patches, in the long run. It took me a while to put this into words but
>> > I was helped by a similar discussion ongoing in the OpenStack community
>> > at the moment [1].
>> > 
>> > [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-May/006220.html
>> > 
>> > Signed-off-by: Stephen Finucane <stephen at that.guru>
>> > Cc: Daniel Axtens <dja at axtens.net>
>> > ---
>> >  docs/development/releasing.rst | 27 +++++++++++++++++++++++++++
>> >  1 file changed, 27 insertions(+)
>> > 
>> > diff --git a/docs/development/releasing.rst b/docs/development/releasing.rst
>> > index 86cacb3a..8bb6b314 100644
>> > --- a/docs/development/releasing.rst
>> > +++ b/docs/development/releasing.rst
>> > @@ -115,3 +115,30 @@ when committing::
>> >  
>> >  When enough patches have been backported, you should release a new **PATCH**
>> >  release.
>> > +
>> > +Backport criteria
>> > +~~~~~~~~~~~~~~~~~
>> > +
>> > +We consider bug fixes and security updates to the Patchwork code itself valid
>> > +for backporting, along with fixes to documentation and developer tooling. We do
>> > +not, however, consider the following backportable:
>> > +
>> > +Features
>> > +  Backporting features is complicated and introduces instability in what is
>> > +  supposed to be stable release. If new features are required, users should
>> > +  update their Patchwork version.
>> 
>> Agreed.
>> 
>> > +
>> > +API changes
>> > +  Except for bug fixes that resolve 5xx-class errors or fix security issues.
>> > +  This also applies to API versions.
>> 
>> Agreed. (Unless I've misread it, the first line is incomplete: except
>> for ..., what? I know from context that the 'what' is no backports, but
>> it's not clear from the text.)
>> 
>> > +
>> > +Requirement changes
>> > +  Requirements on a stable branch are provided as a "snapshot in time" and, as
>> > +  with features, should not change so as to prevent instability being introduced
>> > +  in a stable branch. In addition, stable requirements are not a mechanism to
>> > +  alert users to security vulnerabilities and should not be considered as such.
>> 
>> I don't think I really buy the idea that a snapshot in time is a
>> particularly useful or meaningful way of conceptualising an individual
>> software component's release in large and highly interdependent
>> systems. But, I don't think that's worth litigating here in light of the
>> carve-out for distro support below.
>> 
>> I am with you on the "In addition" part.
>> 
>> > +  Users of stable branches should either rely on distro-provided dependencies,
>> > +  which generally maintain a snapshot-in-time fork of packages and selectively
>> > +  backport fixes to them, or manage dependencies manually. In cases, where using
>> (no comma needed after cases?)
>> 
>> > +  a distro-provided package necessitates minor changes to the Patchwork code,
>> > +  these can be discussed on a case-by-case basis.
>> 
>> I think this is generally OK. I would have made a stronger statement
>> about merging small patches to support distro-provided packages if I had
>> written it, but I think the practical upshot of our development process
>> means that discussion (or at least evaluation) of patches on a
>> case-by-case basis is an accurate description of what will inevitably
>> need to occur to get patches in to stable trees.
>> 
>> I'd be really wary about suggesting that people manage dependencies
>> themselves, as they then take on the burden of tracking security updates
>> for their systems themselves and this is hard work.
>
> Fair point. Realistically, any self-respecting sysadmin is going to
> rely on distro packages or always use the latest and greatest version
> of all dependencies though. The reason for including this is to handle
> the people who insist on using virtualenvs or similar to manage their
> dependencies.
>
Okie dokie.


>> One final though I had: when I was working for Canonical in their
>> support engineering team we had rules for what could make it in to
>> stable kernels - https://wiki.ubuntu.com/KernelTeam/KernelUpdates The
>> first four rules are the usual boring sorts of things, critical bug
>> fixes, tracking stable kernel releases, etc.  Their final category for
>> patch acceptance, however, reads:
>> 
>> "$DEITY intervention. Might happen, but very very rarely and will not be
>> explainable."
>> 
>> Do we want a similar thing for if and when we decide to break the rules,
>> or are we right to leave that as implied?
>
> I think we can leave that as implied, given that the decision is
> ultimately going to come down to one of us and I imagine we can explain
> ourselves well enough if necessary.

Yep, no worries, perfectly reasonable call, just wanted to make sure
we'd considered it.

>
> Is this otherwise good to go, so?
>
Yeah I think so.

Acked-by: Daniel Axtens <dja at axtens.net>

Regards,
Daniel
> Stephen
>
>> Regards,
>> Daniel
>> 
>> > -- 
>> > 2.21.0