[PATCH] docs: Document backport criteria

[Daniel Axtens]

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.

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?

Regards,
Daniel

> -- 
> 2.21.0