android-mainline/NOUPSTREAM-ANDROID-README.md.patch - kernel/common-patches - Git at Google

 From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
 From: Todd Kjos <tkjos@google.com>
 Date: Thu, 24 Oct 2019 17:07:24 -0700
 Subject: NOUPSTREAM: ANDROID: README.md

 Add md file to communicate requirements for patches submitted
 to common kernel

 [CPNOTE: 21/07/21] Lee: Androidness

 Change-Id: I92c3d8a6c40d8a8e5e9cfc9cb42887a5a858faf9
 Signed-off-by: Todd Kjos <tkjos@google.com>
 Co-developed-by: Matthias Maennich <maennich@google.com>
 Signed-off-by: Matthias Maennich <maennich@google.com>
 [Lee: Squashing subsequent changes into this initial one]
 Signed-off-by: Lee Jones <lee.jones@linaro.org>
 ---
  README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 150 insertions(+)
  create mode 100644 README.md

 diff --git a/README.md b/README.md
 new file mode 100644
 --- /dev/null
 +++ b/README.md
 @@ -0,0 +1,150 @@
 +# How do I submit patches to Android Common Kernels
 +
 +1. BEST: Make all of your changes to upstream Linux. If appropriate, backport to the stable releases.
 +   These patches will be merged automatically in the corresponding common kernels. If the patch is already
 +   in upstream Linux, post a backport of the patch that conforms to the patch requirements below.
 +   - Do not send patches upstream that contain only symbol exports. To be considered for upstream Linux,
 +additions of `EXPORT_SYMBOL_GPL()` require an in-tree modular driver that uses the symbol -- so include
 +the new driver or changes to an existing driver in the same patchset as the export.
 +   - When sending patches upstream, the commit message must contain a clear case for why the patch
 +is needed and beneficial to the community. Enabling out-of-tree drivers or functionality is not
 +not a persuasive case.
 +
 +2. LESS GOOD: Develop your patches out-of-tree (from an upstream Linux point-of-view). Unless these are
 +   fixing an Android-specific bug, these are very unlikely to be accepted unless they have been
 +   coordinated with kernel-team@android.com. If you want to proceed, post a patch that conforms to the
 +   patch requirements below.
 +
 +# Common Kernel patch requirements
 +
 +- All patches must conform to the Linux kernel coding standards and pass `scripts/checkpatch.pl`
 +- Patches shall not break gki_defconfig or allmodconfig builds for arm, arm64, x86, x86_64 architectures
 +(see  https://source.android.com/setup/build/building-kernels)
 +- If the patch is not merged from an upstream branch, the subject must be tagged with the type of patch:
 +`UPSTREAM:`, `BACKPORT:`, `FROMGIT:`, `FROMLIST:`, or `ANDROID:`.
 +- All patches must have a `Change-Id:` tag (see https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
 +- If an Android bug has been assigned, there must be a `Bug:` tag.
 +- All patches must have a `Signed-off-by:` tag by the author and the submitter
 +
 +Additional requirements are listed below based on patch type
 +
 +## Requirements for backports from mainline Linux: `UPSTREAM:`, `BACKPORT:`
 +
 +- If the patch is a cherry-pick from Linux mainline with no changes at all
 +    - tag the patch subject with `UPSTREAM:`.
 +    - add upstream commit information with a `(cherry picked from commit ...)` line
 +    - Example:
 +        - if the upstream commit message is
 +```
 +        important patch from upstream
 +
 +        This is the detailed description of the important patch
 +
 +        Signed-off-by: Fred Jones <fred.jones@foo.org>
 +```
 +>- then Joe Smith would upload the patch for the common kernel as
 +```
 +        UPSTREAM: important patch from upstream
 +
 +        This is the detailed description of the important patch
 +
 +        Signed-off-by: Fred Jones <fred.jones@foo.org>
 +
 +        Bug: 135791357
 +        Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
 +        (cherry picked from commit c31e73121f4c1ec41143423ac6ce3ce6dafdcec1)
 +        Signed-off-by: Joe Smith <joe.smith@foo.org>
 +```
 +
 +- If the patch requires any changes from the upstream version, tag the patch with `BACKPORT:`
 +instead of `UPSTREAM:`.
 +    - use the same tags as `UPSTREAM:`
 +    - add comments about the changes under the `(cherry picked from commit ...)` line
 +    - Example:
 +```
 +        BACKPORT: important patch from upstream
 +
 +        This is the detailed description of the important patch
 +
 +        Signed-off-by: Fred Jones <fred.jones@foo.org>
 +
 +        Bug: 135791357
 +        Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
 +        (cherry picked from commit c31e73121f4c1ec41143423ac6ce3ce6dafdcec1)
 +        [joe: Resolved minor conflict in drivers/foo/bar.c ]
 +        Signed-off-by: Joe Smith <joe.smith@foo.org>
 +```
 +
 +## Requirements for other backports: `FROMGIT:`, `FROMLIST:`,
 +
 +- If the patch has been merged into an upstream maintainer tree, but has not yet
 +been merged into Linux mainline
 +    - tag the patch subject with `FROMGIT:`
 +    - add info on where the patch came from as `(cherry picked from commit <sha1> <repo> <branch>)`. This
 +must be a stable maintainer branch (not rebased, so don't use `linux-next` for example).
 +    - if changes were required, use `BACKPORT: FROMGIT:`
 +    - Example:
 +        - if the commit message in the maintainer tree is
 +```
 +        important patch from upstream
 +
 +        This is the detailed description of the important patch
 +
 +        Signed-off-by: Fred Jones <fred.jones@foo.org>
 +```
 +>- then Joe Smith would upload the patch for the common kernel as
 +```
 +        FROMGIT: important patch from upstream
 +
 +        This is the detailed description of the important patch
 +
 +        Signed-off-by: Fred Jones <fred.jones@foo.org>
 +
 +        Bug: 135791357
 +        (cherry picked from commit 878a2fd9de10b03d11d2f622250285c7e63deace
 +         https://git.kernel.org/pub/scm/linux/kernel/git/foo/bar.git test-branch)
 +        Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
 +        Signed-off-by: Joe Smith <joe.smith@foo.org>
 +```
 +
 +
 +- If the patch has been submitted to LKML, but not accepted into any maintainer tree
 +    - tag the patch subject with `FROMLIST:`
 +    - add a `Link:` tag with a link to the submittal on lore.kernel.org
 +    - add a `Bug:` tag with the Android bug (required for patches not accepted into
 +a maintainer tree)
 +    - if changes were required, use `BACKPORT: FROMLIST:`
 +    - Example:
 +```
 +        FROMLIST: important patch from upstream
 +
 +        This is the detailed description of the important patch
 +
 +        Signed-off-by: Fred Jones <fred.jones@foo.org>
 +
 +        Bug: 135791357
 +        Link: https://lore.kernel.org/lkml/20190619171517.GA17557@someone.com/
 +        Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
 +        Signed-off-by: Joe Smith <joe.smith@foo.org>
 +```
 +
 +## Requirements for Android-specific patches: `ANDROID:`
 +
 +- If the patch is fixing a bug to Android-specific code
 +    - tag the patch subject with `ANDROID:`
 +    - add a `Fixes:` tag that cites the patch with the bug
 +    - Example:
 +```
 +        ANDROID: fix android-specific bug in foobar.c
 +
 +        This is the detailed description of the important fix
 +
 +        Fixes: 1234abcd2468 ("foobar: add cool feature")
 +        Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
 +        Signed-off-by: Joe Smith <joe.smith@foo.org>
 +```
 +
 +- If the patch is a new feature
 +    - tag the patch subject with `ANDROID:`
 +    - add a `Bug:` tag with the Android bug (required for android-specific features)
 +
	From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
	From: Todd Kjos <tkjos@google.com>
	Date: Thu, 24 Oct 2019 17:07:24 -0700
	Subject: NOUPSTREAM: ANDROID: README.md

	Add md file to communicate requirements for patches submitted
	to common kernel

	[CPNOTE: 21/07/21] Lee: Androidness

	Change-Id: I92c3d8a6c40d8a8e5e9cfc9cb42887a5a858faf9
	Signed-off-by: Todd Kjos <tkjos@google.com>
	Co-developed-by: Matthias Maennich <maennich@google.com>
	Signed-off-by: Matthias Maennich <maennich@google.com>
	[Lee: Squashing subsequent changes into this initial one]
	Signed-off-by: Lee Jones <lee.jones@linaro.org>
	---
	README.md \| 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
	1 file changed, 150 insertions(+)
	create mode 100644 README.md

	diff --git a/README.md b/README.md
	new file mode 100644
	--- /dev/null
	+++ b/README.md
	@@ -0,0 +1,150 @@
	+# How do I submit patches to Android Common Kernels
	+
	+1. BEST: Make all of your changes to upstream Linux. If appropriate, backport to the stable releases.
	+ These patches will be merged automatically in the corresponding common kernels. If the patch is already
	+ in upstream Linux, post a backport of the patch that conforms to the patch requirements below.
	+ - Do not send patches upstream that contain only symbol exports. To be considered for upstream Linux,
	+additions of `EXPORT_SYMBOL_GPL()` require an in-tree modular driver that uses the symbol -- so include
	+the new driver or changes to an existing driver in the same patchset as the export.
	+ - When sending patches upstream, the commit message must contain a clear case for why the patch
	+is needed and beneficial to the community. Enabling out-of-tree drivers or functionality is not
	+not a persuasive case.
	+
	+2. LESS GOOD: Develop your patches out-of-tree (from an upstream Linux point-of-view). Unless these are
	+ fixing an Android-specific bug, these are very unlikely to be accepted unless they have been
	+ coordinated with kernel-team@android.com. If you want to proceed, post a patch that conforms to the
	+ patch requirements below.
	+
	+# Common Kernel patch requirements
	+
	+- All patches must conform to the Linux kernel coding standards and pass `scripts/checkpatch.pl`
	+- Patches shall not break gki_defconfig or allmodconfig builds for arm, arm64, x86, x86_64 architectures
	+(see https://source.android.com/setup/build/building-kernels)
	+- If the patch is not merged from an upstream branch, the subject must be tagged with the type of patch:
	+`UPSTREAM:`, `BACKPORT:`, `FROMGIT:`, `FROMLIST:`, or `ANDROID:`.
	+- All patches must have a `Change-Id:` tag (see https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
	+- If an Android bug has been assigned, there must be a `Bug:` tag.
	+- All patches must have a `Signed-off-by:` tag by the author and the submitter
	+
	+Additional requirements are listed below based on patch type
	+
	+## Requirements for backports from mainline Linux: `UPSTREAM:`, `BACKPORT:`
	+
	+- If the patch is a cherry-pick from Linux mainline with no changes at all
	+ - tag the patch subject with `UPSTREAM:`.
	+ - add upstream commit information with a `(cherry picked from commit ...)` line
	+ - Example:
	+ - if the upstream commit message is
	+```
	+ important patch from upstream
	+
	+ This is the detailed description of the important patch
	+
	+ Signed-off-by: Fred Jones <fred.jones@foo.org>
	+```
	+>- then Joe Smith would upload the patch for the common kernel as
	+```
	+ UPSTREAM: important patch from upstream
	+
	+ This is the detailed description of the important patch
	+
	+ Signed-off-by: Fred Jones <fred.jones@foo.org>
	+
	+ Bug: 135791357
	+ Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
	+ (cherry picked from commit c31e73121f4c1ec41143423ac6ce3ce6dafdcec1)
	+ Signed-off-by: Joe Smith <joe.smith@foo.org>
	+```
	+
	+- If the patch requires any changes from the upstream version, tag the patch with `BACKPORT:`
	+instead of `UPSTREAM:`.
	+ - use the same tags as `UPSTREAM:`
	+ - add comments about the changes under the `(cherry picked from commit ...)` line
	+ - Example:
	+```
	+ BACKPORT: important patch from upstream
	+
	+ This is the detailed description of the important patch
	+
	+ Signed-off-by: Fred Jones <fred.jones@foo.org>
	+
	+ Bug: 135791357
	+ Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
	+ (cherry picked from commit c31e73121f4c1ec41143423ac6ce3ce6dafdcec1)
	+ [joe: Resolved minor conflict in drivers/foo/bar.c ]
	+ Signed-off-by: Joe Smith <joe.smith@foo.org>
	+```
	+
	+## Requirements for other backports: `FROMGIT:`, `FROMLIST:`,
	+
	+- If the patch has been merged into an upstream maintainer tree, but has not yet
	+been merged into Linux mainline
	+ - tag the patch subject with `FROMGIT:`
	+ - add info on where the patch came from as `(cherry picked from commit <sha1> <repo> <branch>)`. This
	+must be a stable maintainer branch (not rebased, so don't use `linux-next` for example).
	+ - if changes were required, use `BACKPORT: FROMGIT:`
	+ - Example:
	+ - if the commit message in the maintainer tree is
	+```
	+ important patch from upstream
	+
	+ This is the detailed description of the important patch
	+
	+ Signed-off-by: Fred Jones <fred.jones@foo.org>
	+```
	+>- then Joe Smith would upload the patch for the common kernel as
	+```
	+ FROMGIT: important patch from upstream
	+
	+ This is the detailed description of the important patch
	+
	+ Signed-off-by: Fred Jones <fred.jones@foo.org>
	+
	+ Bug: 135791357
	+ (cherry picked from commit 878a2fd9de10b03d11d2f622250285c7e63deace
	+ https://git.kernel.org/pub/scm/linux/kernel/git/foo/bar.git test-branch)
	+ Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
	+ Signed-off-by: Joe Smith <joe.smith@foo.org>
	+```
	+
	+
	+- If the patch has been submitted to LKML, but not accepted into any maintainer tree
	+ - tag the patch subject with `FROMLIST:`
	+ - add a `Link:` tag with a link to the submittal on lore.kernel.org
	+ - add a `Bug:` tag with the Android bug (required for patches not accepted into
	+a maintainer tree)
	+ - if changes were required, use `BACKPORT: FROMLIST:`
	+ - Example:
	+```
	+ FROMLIST: important patch from upstream
	+
	+ This is the detailed description of the important patch
	+
	+ Signed-off-by: Fred Jones <fred.jones@foo.org>
	+
	+ Bug: 135791357
	+ Link: https://lore.kernel.org/lkml/20190619171517.GA17557@someone.com/
	+ Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
	+ Signed-off-by: Joe Smith <joe.smith@foo.org>
	+```
	+
	+## Requirements for Android-specific patches: `ANDROID:`
	+
	+- If the patch is fixing a bug to Android-specific code
	+ - tag the patch subject with `ANDROID:`
	+ - add a `Fixes:` tag that cites the patch with the bug
	+ - Example:
	+```
	+ ANDROID: fix android-specific bug in foobar.c
	+
	+ This is the detailed description of the important fix
	+
	+ Fixes: 1234abcd2468 ("foobar: add cool feature")
	+ Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
	+ Signed-off-by: Joe Smith <joe.smith@foo.org>
	+```
	+
	+- If the patch is a new feature
	+ - tag the patch subject with `ANDROID:`
	+ - add a `Bug:` tag with the Android bug (required for android-specific features)
	+