docs: Document backport criteria
diff mbox series

Message ID 20190514150727.15840-1-stephen@that.guru
State Accepted
Headers show
Series
  • docs: Document backport criteria
Related show

Commit Message

Stephen Finucane May 14, 2019, 3:07 p.m. UTC
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@that.guru>
Cc: Daniel Axtens <dja@axtens.net>
---
 docs/development/releasing.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

Comments

Daniel Axtens May 14, 2019, 5 p.m. UTC | #1
Stephen Finucane <stephen@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@that.guru>
> Cc: Daniel Axtens <dja@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
Stephen Finucane May 23, 2019, 10:43 a.m. UTC | #2
On Wed, 2019-05-15 at 03:00 +1000, Daniel Axtens wrote:
> Stephen Finucane <stephen@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@that.guru>
> > Cc: Daniel Axtens <dja@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
Daniel Axtens May 24, 2019, 4:07 a.m. UTC | #3
Stephen Finucane <stephen@that.guru> writes:

> On Wed, 2019-05-15 at 03:00 +1000, Daniel Axtens wrote:
>> Stephen Finucane <stephen@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@that.guru>
>> > Cc: Daniel Axtens <dja@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@axtens.net>

Regards,
Daniel
> Stephen
>
>> Regards,
>> Daniel
>> 
>> > -- 
>> > 2.21.0
Stephen Finucane May 24, 2019, 2:49 p.m. UTC | #4
On Fri, 2019-05-24 at 14:07 +1000, Daniel Axtens wrote:
> Stephen Finucane <stephen@that.guru> writes:
> 
> > On Wed, 2019-05-15 at 03:00 +1000, Daniel Axtens wrote:
> > > Stephen Finucane <stephen@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@that.guru>
> > > > Cc: Daniel Axtens <dja@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@axtens.net>

Excellent. Thanks!

Stephen

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

Patch
diff mbox series

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.
+
+API changes
+  Except for bug fixes that resolve 5xx-class errors or fix security issues.
+  This also applies to API versions.
+
+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.
+  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
+  a distro-provided package necessitates minor changes to the Patchwork code,
+  these can be discussed on a case-by-case basis.