Some pointers on how to get a patch into stable.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---

This probably needs more love, but I'd like to have at least _some_
kind of documentation.

Maybe this should also go into the wiki?

---
 docs/stable-process.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/stable-process.rst

diff --git a/docs/stable-process.rst b/docs/stable-process.rst
new file mode 100644
index 0000000000..2502823dc5
--- /dev/null
+++ b/docs/stable-process.rst
@@ -0,0 +1,57 @@
+QEMU and the stable process
+===========================
+
+QEMU stable releases
+--------------------
+
+QEMU stable releases are based upon the last released QEMU version
+and marked by an additional version number, e.g. 2.10.1. Occasionally,
+a four-number version is released, if a single urgent fix needs to go
+on top.
+
+Usually, a stable release is only done for the last released version.
+
+What should go into a stable release?
+-------------------------------------
+
+Generally, the following patches are considered stable material:
+- Patches that fix severe issues, like fixes for CVEs
+- Patches that fix regressions
+
+If you think the patch would be important for users of the current release
+(or for a distribution picking fixes), it is usually a good candidate
+for stable.
+
+
+How to get a patch into QEMU stable
+-----------------------------------
+
+There are various ways to get a patch into stable:
+
+* Preferred: Make sure that the stable maintainers are on copy when you send
+  the patch by adding
+
+  .. code::
+
+     Cc: qemu-stable@nongnu.org
+
+   to the patch description. This will make git add the stable maintainers
+   on copy when your patch is sent out.
+
+* If a maintainer judges the patch appropriate for stable later on (or you
+  notify them), they will add the same line to your patch, meaning that
+  the stable maintainers will be on copy on the maintainer's pull request.
+
+* If you judge an already merged patch suitable for stable, send a mail
+  to ``qemu-stable@nongnu.org`` with ``qemu-devel@nongnu.org`` and appropriate
+  other people (like the patch author or the relevant maintainer) on copy.
+
+Stable release process
+----------------------
+
+When the stable maintainers prepare a new stable release, they will prepare
+a git branch with a release candidate and send the patches out to
+``qemu-devel@nongnu.org`` for review. If any of your patches are included,
+please verify that they look fine. You may also nominate other patches that
+you think are suitable for inclusion. After review is complete (may involve
+more release candidates), a new stable release is made available.
-- 
2.13.6

Quoting Cornelia Huck (2018-02-09 07:11:12)
> Some pointers on how to get a patch into stable.

Thanks for putting this together. I made some minor suggestions below
that might help clarify some points.

> 
> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> ---
> 
> This probably needs more love, but I'd like to have at least _some_
> kind of documentation.
> 
> Maybe this should also go into the wiki?

We can probably add a reference to it in:

  https://wiki.qemu.org/Contribute/SubmitAPatch

I should probably add a MAINTAINERS entry for stable that references
it too.

> 
> ---
>  docs/stable-process.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 57 insertions(+)
>  create mode 100644 docs/stable-process.rst
> 
> diff --git a/docs/stable-process.rst b/docs/stable-process.rst
> new file mode 100644
> index 0000000000..2502823dc5
> --- /dev/null
> +++ b/docs/stable-process.rst
> @@ -0,0 +1,57 @@
> +QEMU and the stable process
> +===========================
> +
> +QEMU stable releases
> +--------------------
> +
> +QEMU stable releases are based upon the last released QEMU version
> +and marked by an additional version number, e.g. 2.10.1. Occasionally,
> +a four-number version is released, if a single urgent fix needs to go
> +on top.
> +
> +Usually, a stable release is only done for the last released version.

Maybe:

"Usually, stable releases are only provided for the last major QEMU
release. For example, when QEMU 2.11.0 is released, 2.11.x or 2.11.x.y
stable releases are only produced until QEMU 2.12.0 is released, at
which the stable process moves to producing 2.12.x/2.12.x.y releases."


> +
> +What should go into a stable release?
> +-------------------------------------
> +
> +Generally, the following patches are considered stable material:
> +- Patches that fix severe issues, like fixes for CVEs
> +- Patches that fix regressions
> +
> +If you think the patch would be important for users of the current release
> +(or for a distribution picking fixes), it is usually a good candidate
> +for stable.
> +
> +
> +How to get a patch into QEMU stable
> +-----------------------------------
> +
> +There are various ways to get a patch into stable:
> +
> +* Preferred: Make sure that the stable maintainers are on copy when you send
> +  the patch by adding
> +
> +  .. code::
> +
> +     Cc: qemu-stable@nongnu.org
> +
> +   to the patch description. This will make git add the stable maintainers
> +   on copy when your patch is sent out.

"By default, this will send the patch to qemu-stable@nongnu.org if you use
git send-email, which is where patches that are stable candidates are
tracked by the maintainers."

"You can also reply to a patch and Cc: qemu-stable@nongnu.org directly with
your mail client if you think a previously submitted patch should be
considered for a stable release."

> +
> +* If a maintainer judges the patch appropriate for stable later on (or you
> +  notify them), they will add the same line to your patch, meaning that

"to the patch" (in case the Cc'er isn't the author)

> +  the stable maintainers will be on copy on the maintainer's pull request.
> +
> +* If you judge an already merged patch suitable for stable, send a mail

(preferably as a reply to the most recent patch submission)

> +  to ``qemu-stable@nongnu.org`` with ``qemu-devel@nongnu.org`` and appropriate

"along with"

> +  other people (like the patch author or the relevant maintainer) on copy.
> +
> +Stable release process
> +----------------------
> +
> +When the stable maintainers prepare a new stable release, they will prepare
> +a git branch with a release candidate and send the patches out to
> +``qemu-devel@nongnu.org`` for review. If any of your patches are included,

"qemu-devel@nongnu.org and qemu-stable@nongnu.org"

> +please verify that they look fine. You may also nominate other patches that
> +you think are suitable for inclusion. After review is complete (may involve
> +more release candidates), a new stable release is made available.
> -- 
> 2.13.6
> 

On Sun, 11 Feb 2018 21:03:02 -0600
Michael Roth <mdroth@linux.vnet.ibm.com> wrote:

> Quoting Cornelia Huck (2018-02-09 07:11:12)
> > Some pointers on how to get a patch into stable.  
> 
> Thanks for putting this together. I made some minor suggestions below
> that might help clarify some points.
> 
> > 
> > Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> > ---
> > 
> > This probably needs more love, but I'd like to have at least _some_
> > kind of documentation.
> > 
> > Maybe this should also go into the wiki?  
> 
> We can probably add a reference to it in:
> 
>   https://wiki.qemu.org/Contribute/SubmitAPatch

Yes, it makes sense to add a pointer once this is upstream.

> 
> I should probably add a MAINTAINERS entry for stable that references
> it too.

+1

> 
> > 
> > ---
> >  docs/stable-process.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 57 insertions(+)
> >  create mode 100644 docs/stable-process.rst

<snip>

I have incorporated your suggestions (sometimes massaged a bit). v2 on
the way.

Thanks for your feedback!