[PATCH] docs: Document backport criteria

[Stephen Finucane]

On Fri, 2019-05-24 at 14:07 +1000, Daniel Axtens wrote:
> 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>

Excellent. Thanks!

Stephen

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