[PATCH] docs: Document backport criteria

[Stephen Finucane]

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.

> 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.

Is this otherwise good to go, so?

Stephen

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