[Backport wrynose] README.md: provide commit guidelines

AGENTS.md

@@ -129,102 +129,25 @@ We expect every change to be backported to `wrynose` unless it is specific to
 `wrynose` (e.g. it does not apply to `master`, or `master` has diverged in a way
 that makes the change meaningless there).
 
-### Default path: backport from master
+The full backport workflow — the default `git cherry-pick -x` path from
+`master`, the exception for wrynose-only changes, the CI-equivalent checks to
+run before opening a PR, and the `[Backport wrynose]` commit message
+conventions — is documented in [BACKPORTING.md](BACKPORTING.md).
 
-1. Land the change on **master** following the master workflow (fork, topic
-   branch, rebase on latest upstream `master`, open a PR).
-2. Once it is merged on `master`, backport the merged commit(s) to `wrynose`
-   using **`git cherry-pick -x`** so the backport records the original commit
-   hash in the message (`(cherry picked from commit <sha>)`):
+If the change **cannot** be submitted to `master` (it is specific to
+`wrynose`), then submit it directly against `wrynose`, and **explain in the
+commit body and PR description why it is wrynose-only** and not a backport.
+The general contribution workflow and the commit subject and message
+requirements are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
 
-   ```sh
-   git fetch origin
-   git checkout -b backport/<PR-or-topic>-to-wrynose origin/wrynose
-   git cherry-pick -x <sha> [<sha> ...]      # -x records the source commit
-   # resolve conflicts if any, keeping the change minimal and equivalent
-   ```
-
-3. Run the CI-equivalent checks (see below).
-4. Open a GitHub pull request targeting **wrynose**. Follow the project's
-   `[Backport wrynose]` subject convention seen in history (see section 7).
-5. Use PR discussion for review iteration.
-
-### Exception: wrynose-only changes
-
-If the change **cannot** be submitted to `master` (it is specific to `wrynose`),
-then submit it directly against `wrynose`, and **explain in the commit body and
-PR description why it is wrynose-only** and not a backport. This mirrors the
-`README.md` contribution guidance for the stable branch.
-
-### Before opening/updating a wrynose PR
-
-Run CI-equivalent checks in this order:
-
-```sh
-ci/kas-container-shell-helper.sh ci/yocto-patchreview.sh
-ci/kas-container-shell-helper.sh ci/yocto-check-layer.sh
-ci/kas-container-shell-helper.sh ci/oe-selftest.sh
-```
-
-Important:
-
-- Follow Yocto submission guidance referenced in README:
-  [Preparing Changes for Submission](https://docs.yoctoproject.org/dev/contributor-guide/submit-changes.html#preparing-changes-for-submission)
-
-## 7) Commit message best practices (project style)
-
-For **backports**, preserve the original master commit message and metadata, and
-keep the `cherry-pick -x` trailer intact. The branch convention is to prefix the
-subject with `[Backport wrynose]`, as seen in recent history:
-
-- `[Backport wrynose] iq-9075-evk: build sdcc feature DTs as overlays (#2463)`
-- `[Backport wrynose] kgsl-dlkm: Update to v1.0.4 (#2409)`
-- `[Backport wrynose] linux-qcom-6.18 : update to tag qcom-6.18.y-20260611 (#2447)`
-
-The backported body should retain the original explanation and end with the
-cherry-pick trailer that `git cherry-pick -x` adds:
-
-```text
-(cherry picked from commit <sha>)
-```
-
-For the underlying change style (when authoring on `master` before backporting,
-or for wrynose-only changes), use the style seen in recent history:
-
-- `component: imperative summary` (preferred when scoped), e.g.
-  - `ci/qcom-distro: Include meta-dpdk layer (#1902)`
-  - `fit-dtb-compatible: drop SoC version suffixes from compatible strings`
-  - `debug.yml: enable FTrace settings in kernel cmdline (#2155)`
-- Or concise imperative summary when cross-cutting, e.g.
-  - `Drop SoC version suffixes from FIT DTB compatible strings (#2159)`
-
-Every commit **must** include a `Signed-off-by` trailer using the identity from
-the local git configuration:
-
-```sh
-git commit -s   # or pass --signoff; fetches user.name / user.email from git config
-```
-
-`git cherry-pick` preserves the original author's `Signed-off-by`; add your own
-with `git cherry-pick -s` if your workflow requires it. If committing
-programmatically, append the trailer explicitly:
+When committing programmatically, take the `Signed-off-by` identity from the
+local git configuration and append the trailer explicitly:
 
 ```text
 Signed-off-by: $(git config user.name) <$(git config user.email)>
 ```
 
-Never fabricate a name or email; always read from `git config`.
-
-Guidelines:
-
-- Keep subject line short and specific; capture intent, not a file-by-file dump.
-- Use imperative mood (`Add`, `Update`, `Drop`, `Enable`, `Revert`).
-- Add a body for non-trivial changes explaining **why** and key design decisions.
-- Wrap body lines for readability (~72 chars).
-- Use consistent recipe bump wording for version updates, e.g.
-  `recipe-name: Update to vX.Y.Z`.
-- Include PR reference in subject when appropriate: `(#NNNN)`.
-- Avoid mixing unrelated changes in one commit; split logically.
-- Each patch must be logically coherent, self-contained, and independently buildable.
-- The tree must remain in a functional state after every commit.
-- Fixups within the same patch series are not allowed; changes should be corrected in the patch where they are introduced.
+Never fabricate a name or email; always read them from `git config`.
+
+Fixups within the same patch series are not allowed; changes should be
+corrected in the patch where they are introduced.

BACKPORTING.md

@@ -0,0 +1,57 @@
+# Backporting to meta-qcom (wrynose LTS)
+
+`wrynose` is the **LTS Stable branch**. It is not the primary development
+branch: `master` is. Every change is expected to land on `master` first and
+then be **backported** here, unless it is specific to `wrynose` (e.g. it does
+not apply to `master`, or `master` has diverged in a way that makes the change
+meaningless there).
+
+1. Land the change on **master** first, following the master contribution
+   workflow (fork, topic branch, rebase on latest upstream `master`, open a
+   PR).
+2. Once it is merged on `master`, backport the merged commit(s) to `wrynose`
+   using **`git cherry-pick -x`** so the backport records the original commit
+   hash in the message (`(cherry picked from commit <sha>)`):
+
+   ```sh
+   git fetch origin
+   git checkout -b backport/<PR-or-topic>-to-wrynose origin/wrynose
+   git cherry-pick -x <sha> [<sha> ...]      # -x records the source commit
+   # resolve conflicts if any, keeping the change minimal and equivalent
+   ```
+
+3. Run the CI-equivalent checks (see below).
+4. Open a GitHub pull request targeting **wrynose**, following the
+   `[Backport wrynose]` subject convention (see [Commit messages for
+   backports](#commit-messages-for-backports)).
+5. Use PR discussion for review iteration.
+
+## Before opening/updating a backport PR
+
+Run the CI-equivalent checks in this order:
+
+```sh
+ci/kas-container-shell-helper.sh ci/yocto-patchreview.sh
+ci/kas-container-shell-helper.sh ci/yocto-check-layer.sh
+ci/kas-container-shell-helper.sh ci/oe-selftest.sh
+```
+
+## Commit messages for backports
+
+For backports, preserve the original master commit message and metadata, and
+keep the `cherry-pick -x` trailer intact. The branch convention is to prefix
+the subject with `[Backport wrynose]`, as seen in recent history:
+
+- `[Backport wrynose] iq-9075-evk: build sdcc feature DTs as overlays (#2463)`
+- `[Backport wrynose] kgsl-dlkm: Update to v1.0.4 (#2409)`
+- `[Backport wrynose] linux-qcom-6.18 : update to tag qcom-6.18.y-20260611 (#2447)`
+
+The backported body should retain the original explanation and end with the
+cherry-pick trailer that `git cherry-pick -x` adds:
+
+```text
+(cherry picked from commit <sha>)
+```
+
+`git cherry-pick` preserves the original author's `Signed-off-by`; add your own
+with `git cherry-pick -s` if your workflow requires it.

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to meta-qcom (wrynose LTS)
+
+`wrynose` is the LTS Stable branch, so changes should be backported from
+`master` whenever possible rather than submitted here directly. Please prefer
+the backporting process and follow [BACKPORTING.md](BACKPORTING.md) for the
+workflow. Submit a change directly to `wrynose` only when it cannot be applied
+to `master`, and include the necessary explanation.
+
+For some useful guidelines when submitting patches, please refer to:
+[Preparing Changes for Submission](https://docs.yoctoproject.org/dev/contributor-guide/submit-changes.html#preparing-changes-for-submission)
+
+Pull requests will be discussed within the GitHub pull-request infrastructure.
+
+## Commit messages
+
+Each commit must be atomic: it must contain exactly one logical change. Do not
+squash multiple features, fixes, or otherwise unrelated changes into a single
+commit — split them into separate commits, one per logical change. Each patch
+must be logically coherent, self-contained, and independently buildable, and
+the tree must remain in a functional state after every commit.
+
+Each commit must contain a well-formed commit subject and message.
+
+The commit subject must follow the form `recipe-name: summary of the changes`,
+where `recipe-name` identifies the recipe or component being touched and the
+summary concisely describes the change. Keep the subject short and specific,
+capturing intent rather than a file-by-file dump. For example:
+
+- `ci/qcom-distro: Include meta-dpdk layer`
+- `fit-dtb-compatible: drop SoC version suffixes from compatible strings`
+- `debug.yml: enable FTrace settings in kernel cmdline`
+
+Use consistent wording for version upgrades, e.g.
+`recipe-name: upgrade vX.Y.Z -> vA.B.C`.
+
+The commit message (the body) must:
+
+- be written in plain English;
+- first describe the issue or the problem that is being solved, so that a
+  reader can understand *why* the change is needed;
+- then use the imperative mood (e.g. "add", "drop", "enable", "update")
+  to describe the actions to be performed in order to solve the problem;
+- not merely restate *what* the diff changes line by line — the diff
+  already shows that;
+- avoid unnecessary bullet lists; prefer prose paragraphs;
+- wrap body lines for readability (~72 chars).
+
+## Sign-off and trailers
+
+Every commit must also carry a `Signed-off-by` trailer matching the
+author identity from your local `git config` (use `git commit -s`). Never
+fabricate a name or email; always read them from `git config`.
+
+If an AI coding assistant or other advanced tool was used to help create the
+change, acknowledge that use by adding an `Assisted-by` trailer in the form:
+
+```text
+Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+```
+
+Where `AGENT_NAME` is the name of the AI tool or framework, `MODEL_VERSION` is
+the specific model version used, and `[TOOL1] [TOOL2]` are optional specialized
+analysis tools. Basic development tools (git, gcc, make, editors) should not be
+listed. For example:
+
+```text
+Assisted-by: ExampleAgent:example-model-1.0
+```

README.md

@@ -149,14 +149,13 @@ by using the GitHub pull-request feature. Fork the repo, create a branch,
 do the work, rebase from upstream, and create the pull request.
 
 On the stable (branch **wrynose**) patches should be integrated as a backport
-whenever possible, and for that they must follow the (branch **master**) process.
+whenever possible. See [BACKPORTING.md](BACKPORTING.md) for the backport
+workflow.
+
 If the changes cannot be submitted to (branch **master**), then they must be
 submitted to (branch **wrynose**), including the necessary explanation.
-
-For some useful guidelines when submitting patches, please refer to:
-[Preparing Changes for Submission](https://docs.yoctoproject.org/dev/contributor-guide/submit-changes.html#preparing-changes-for-submission)
-
-Pull requests will be discussed within the GitHub pull-request infrastructure.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow
+and the commit subject and message requirements before opening a pull request.
 
 Branch **kirkstone** is not open for direct contributions, please raise an
 issue with the suggested change instead.