Patchwork [RFC] Add SUBMITTING_PATCHES

login
register
mail settings
Submitter Blue Swirl
Date Sept. 13, 2009, 5:02 p.m.
Message ID <f43fc5580909131002ob6e8385gdec9e2e0289acba2@mail.gmail.com>
Download mbox | patch
Permalink /patch/33552/
State Superseded
Headers show

Comments

Blue Swirl - Sept. 13, 2009, 5:02 p.m.
Problem: Patches are submitted in a way that causes burden for the committer.

Solution: Inform patch submitters about more helpful way.

Signed-off-by: Blue Swirl <blauwirbel@gmail.com>
---
Changes since previous version:
* Removed SoB exception for small patches
* Removed quilt from list of applying tools
* Added SP7.2

 SUBMITTING_PATCHES |  115 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 115 insertions(+), 0 deletions(-)
 create mode 100644 SUBMITTING_PATCHES
Kirill A. Shutemov - Sept. 14, 2009, 4:30 a.m.
On Sun, Sep 13, 2009 at 8:02 PM, Blue Swirl <blauwirbel@gmail.com> wrote:
> Problem: Patches are submitted in a way that causes burden for the committer.
>
> Solution: Inform patch submitters about more helpful way.

I think patchset versioning and [RESEND] should be also covered in this howto.

>
> Signed-off-by: Blue Swirl <blauwirbel@gmail.com>
> ---
> Changes since previous version:
> * Removed SoB exception for small patches
> * Removed quilt from list of applying tools
> * Added SP7.2
>
>  SUBMITTING_PATCHES |  115 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 115 insertions(+), 0 deletions(-)
>  create mode 100644 SUBMITTING_PATCHES
>
> diff --git a/SUBMITTING_PATCHES b/SUBMITTING_PATCHES
> new file mode 100644
> index 0000000..10f6db7
> --- /dev/null
> +++ b/SUBMITTING_PATCHES
> @@ -0,0 +1,115 @@
> +Whereas the QEMU developers highly appreciate any patches, it would be
> +most helpful for all parties if the following rules were followed in
> +order to simplify mechanical extraction and applying of the
> +patches. Patch management utilities (git send-email, quilt, and
> +similar) can assist in producing compatible patches and patch sets
> +with correct formatting etc., so their use is recommended.
> +
> +1. Format of e-mail subject
> +
> +SP1.1: The e-mail subject must contain "PATCH" in brackets, followed
> +by white space and a short summary of the change.
> +
> +SP1.2: The bracketed text may also include other commonly used tags
> +separated with a comma and white space, including "RFC" (Request for
> +Comments, for patches submitted for discussion and review purposes
> +only) and "RFT" (Request for Testing, for patches which are suspected
> +to introduce problems in use cases which have not been tested by the
> +submitter).
> +
> +SP1.3: The summary must be suitable for changelog as is (start with a
> +capital letter etc.) after deleting the bracketed text, white space
> +after it and any text preceding it.
> +
> +2. Format of e-mail body
> +
> +SP2.1: The e-mail body must contain a description of the change,
> +suitable for changelog without any editing.
> +
> +SP2.2: The patch description must be selfstanding (not depend on other
> +patches, other messages or background discussion).
> +
> +SP2.3: The description must be followed by one blank line and a
> +"Signed-off-by:" line.
> +
> +SP2.4: Optionally, the "Signed-off-by:" line may be followed with a
> +line with only "---" and on the following lines, other comments not
> +intended for changelog (for example diffstat, location of a git tree,
> +whether the patch is also directed towards stable tree, witty
> +signature etc.).
> +
> +SP2.5: Exception: The rules in this section are not applicable for
> +patches tagged with "RFC" or "RFT"
> +
> +3. Attaching patches to e-mail
> +
> +SP3.1: Each message may contain only one patch
> +
> +SP3.2: If possible, please send the patch inlined (to make commenting
> +easier) and also attached (to make it easier to apply)
> +
> +SP3.2: If the patch is attached (and not inlined) it should be marked
> +as text/plain content type
> +
> +SP3.3: Please ensure in advance that your e-mail tool does not mangle
> +white space or break long lines
> +
> +4. About patches
> +
> +SP4.1: It must be possible to apply the patch with "git am" without
> +any editing or extra flags (git config apply.whitespace=fix).
> +
> +SP4.2: The patch must be based in the QEMU root directory (not for
> +example KVM, Xen or lower level subdirectory)
> +
> +SP4.3: The patches targeted for development branch must be based on
> +the current development repository.
> +
> +SP4.4: The patches targeted for stable branch must be based on the
> +current stable repository.
> +
> +5. Changes made by the patch
> +
> +SP5.1: Do not combine formatting changes with functional changes.
> +
> +SP5.2: Do not combine several independent functional changes to one
> +patch unless required by the logic of the changes.
> +
> +SP5.3: The changes may not introduce new violations of CODING_STYLE.
> +
> +SP5.4: If the changes involve new or changed user interface,
> +documentation and help messages must be changed as well.
> +
> +SP5.5: If the changes add new files, make sure that the patch includes
> +them (for example, use diff flag -N).
> +
> +SP5.6 Please check that the changes do not introduce new warnings to
> +be emitted when compiling the sources, preferably not even when
> +compiling with Sparse checker.
> +
> +6. Series of patches
> +
> +SP6.1 Patch series should be numbered with the number included inside
> +the brackets in the subject (for example "[PATCH 09/17]").
> +
> +SP6.2: The patch series should include a cover letter describing the
> +patchset in general (as opposed to individual patch descriptions).
> +
> +SP6.3: No changes in a single patch in the patch series may break the
> +ability to bisect (make sure that when applying the patches
> +sequentially step by step, working executables can be produced at each
> +step and not only at the final step).
> +
> +
> +7. Legal aspects
> +
> +SP7.1: Any new files or merges from other sources must be licenced
> +with licences compatible with QEMU licencing (for example, GPLv3 or
> +CDDL are not compatible).
> +
> +SP7.2: Any new files must mention its licence unless it is technically
> +impossible.
> +
> +SP7.3: The "Signed-off-by:" line is a form of legal declaration which
> +the submitter must be aware of (please see Linux
> +Documentation/SubmittingPatches).
> --
> 1.6.2.4
>
>
>

Patch

diff --git a/SUBMITTING_PATCHES b/SUBMITTING_PATCHES
new file mode 100644
index 0000000..10f6db7
--- /dev/null
+++ b/SUBMITTING_PATCHES
@@ -0,0 +1,115 @@ 
+Whereas the QEMU developers highly appreciate any patches, it would be
+most helpful for all parties if the following rules were followed in
+order to simplify mechanical extraction and applying of the
+patches. Patch management utilities (git send-email, quilt, and
+similar) can assist in producing compatible patches and patch sets
+with correct formatting etc., so their use is recommended.
+
+1. Format of e-mail subject
+
+SP1.1: The e-mail subject must contain "PATCH" in brackets, followed
+by white space and a short summary of the change.
+
+SP1.2: The bracketed text may also include other commonly used tags
+separated with a comma and white space, including "RFC" (Request for
+Comments, for patches submitted for discussion and review purposes
+only) and "RFT" (Request for Testing, for patches which are suspected
+to introduce problems in use cases which have not been tested by the
+submitter).
+
+SP1.3: The summary must be suitable for changelog as is (start with a
+capital letter etc.) after deleting the bracketed text, white space
+after it and any text preceding it.
+
+2. Format of e-mail body
+
+SP2.1: The e-mail body must contain a description of the change,
+suitable for changelog without any editing.
+
+SP2.2: The patch description must be selfstanding (not depend on other
+patches, other messages or background discussion).
+
+SP2.3: The description must be followed by one blank line and a
+"Signed-off-by:" line.
+
+SP2.4: Optionally, the "Signed-off-by:" line may be followed with a
+line with only "---" and on the following lines, other comments not
+intended for changelog (for example diffstat, location of a git tree,
+whether the patch is also directed towards stable tree, witty
+signature etc.).
+
+SP2.5: Exception: The rules in this section are not applicable for
+patches tagged with "RFC" or "RFT"
+
+3. Attaching patches to e-mail
+
+SP3.1: Each message may contain only one patch
+
+SP3.2: If possible, please send the patch inlined (to make commenting
+easier) and also attached (to make it easier to apply)
+
+SP3.2: If the patch is attached (and not inlined) it should be marked
+as text/plain content type
+
+SP3.3: Please ensure in advance that your e-mail tool does not mangle
+white space or break long lines
+
+4. About patches
+
+SP4.1: It must be possible to apply the patch with "git am" without
+any editing or extra flags (git config apply.whitespace=fix).
+
+SP4.2: The patch must be based in the QEMU root directory (not for
+example KVM, Xen or lower level subdirectory)
+
+SP4.3: The patches targeted for development branch must be based on
+the current development repository.
+
+SP4.4: The patches targeted for stable branch must be based on the
+current stable repository.
+
+5. Changes made by the patch
+
+SP5.1: Do not combine formatting changes with functional changes.
+
+SP5.2: Do not combine several independent functional changes to one
+patch unless required by the logic of the changes.
+
+SP5.3: The changes may not introduce new violations of CODING_STYLE.
+
+SP5.4: If the changes involve new or changed user interface,
+documentation and help messages must be changed as well.
+
+SP5.5: If the changes add new files, make sure that the patch includes
+them (for example, use diff flag -N).
+
+SP5.6 Please check that the changes do not introduce new warnings to
+be emitted when compiling the sources, preferably not even when
+compiling with Sparse checker.
+
+6. Series of patches
+
+SP6.1 Patch series should be numbered with the number included inside
+the brackets in the subject (for example "[PATCH 09/17]").
+
+SP6.2: The patch series should include a cover letter describing the
+patchset in general (as opposed to individual patch descriptions).
+
+SP6.3: No changes in a single patch in the patch series may break the
+ability to bisect (make sure that when applying the patches
+sequentially step by step, working executables can be produced at each
+step and not only at the final step).
+
+
+7. Legal aspects
+
+SP7.1: Any new files or merges from other sources must be licenced
+with licences compatible with QEMU licencing (for example, GPLv3 or
+CDDL are not compatible).
+
+SP7.2: Any new files must mention its licence unless it is technically
+impossible.
+
+SP7.3: The "Signed-off-by:" line is a form of legal declaration which
+the submitter must be aware of (please see Linux
+Documentation/SubmittingPatches).