Skip to content

AGENTS.md: document the enforced commit conventions#2418

Open
0x1 (EmbeddedAndroid) wants to merge 2 commits into
qualcomm-linux:masterfrom
EmbeddedAndroid:agents-update
Open

AGENTS.md: document the enforced commit conventions#2418
0x1 (EmbeddedAndroid) wants to merge 2 commits into
qualcomm-linux:masterfrom
EmbeddedAndroid:agents-update

Conversation

@EmbeddedAndroid

Copy link
Copy Markdown
Contributor

Going back over the last year of reviews, I noticed several conventions that the maintainers enforce which are not written down in our new Agents.md. Add them alongside the existing commit-message guidance:

  • the Signed-off-by identity must match the author and be a real, routable address rather than a GitHub web-editor noreply
  • subjects use a lowercase component prefix rather than Conventional Commits or kernel-tree prefixes
  • branches are rebased on master rather than merged
  • and added patch files carry an Upstream-Status header.

I'm happy to adjust if some of these rules seem too strict.

Writing these down keeps commits consistent and is the groundwork for enforcing the deterministic subset automatically in the very short future.

Going back over the last year of reviews, several conventions that the
maintainers enforce are not written down here. Add them alongside the
existing commit-message guidance: the Signed-off-by identity must match
the author and be a real, routable address rather than a GitHub
web-editor noreply; subjects use a lowercase component prefix rather
than Conventional Commits or kernel-tree prefixes; branches are rebased
on master rather than merged; and added patch files carry an
Upstream-Status header.

Writing these down keeps commits consistent and is the groundwork for
enforcing the deterministic subset automatically later on.

Signed-off-by: Tyler Baker <tyler.baker@oss.qualcomm.com>
@lumag

Copy link
Copy Markdown
Contributor

As you are writing the docs, would you also mind a human-targeted set of recommendations to author the commits?
Main points:

  • Each commit should contain an atomic set of changes, "Foo also bar and, as we are at it, baz" is a bad idea
  • Each commit message should start by describing the problem or the issue that is being solved.
  • Other useful tips and requirements (valid SoB chain, git cherry-pick -x for backport commits, use of -s if one picksor aplies commit authored by somebody else, etc.).

The rules above list what is rejected, but do not give a human a short
set of recommendations for writing a good commit and series. Add one:
keep each commit atomic, start the message with the problem being
solved, keep a valid Signed-off-by chain, add your own sign-off when
you pick or apply someone else's commit, and use git cherry-pick -x
for backports.

Signed-off-by: Tyler Baker <tyler.baker@oss.qualcomm.com>
@EmbeddedAndroid

Copy link
Copy Markdown
Contributor Author

As you are writing the docs, would you also mind a human-targeted set of recommendations to author the commits? Main points:

  • Each commit should contain an atomic set of changes, "Foo also bar and, as we are at it, baz" is a bad idea
  • Each commit message should start by describing the problem or the issue that is being solved.
  • Other useful tips and requirements (valid SoB chain, git cherry-pick -x for backport commits, use of -s if one picksor aplies commit authored by somebody else, etc.).

Good idea, added as 2b91af9

Comment thread AGENTS.md
commits in a pull request are rejected.
- Every patch file added under a recipe must carry an `Upstream-Status:` header
with a valid value (`Submitted`, `Backport`, `Pending`, `Inappropriate`,
`Denied`, `Accepted`).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here we should include all the valid patterns, and it is missing Inactive-Upstream.

@ricardosalveti

Copy link
Copy Markdown
Contributor

As you are writing the docs, would you also mind a human-targeted set of recommendations to author the commits? Main points:

  • Each commit should contain an atomic set of changes, "Foo also bar and, as we are at it, baz" is a bad idea
  • Each commit message should start by describing the problem or the issue that is being solved.
  • Other useful tips and requirements (valid SoB chain, git cherry-pick -x for backport commits, use of -s if one picksor aplies commit authored by somebody else, etc.).

Good idea, added as 2b91af9

I would prefer if we could keep this part outside AGENTS.md, as this is for humans and it contains a bit of duplication, which would just burn tokens.

We could extend https://github.com/qualcomm-linux/meta-qcom/blob/master/README.md#contributing or just add a new entry at https://github.com/qualcomm-linux/meta-qcom/tree/master/docs.

@lumag

Copy link
Copy Markdown
Contributor

I think a separate document is the best idea.

@lumag

Copy link
Copy Markdown
Contributor

Granted the lack of updates for 3 weeks I've proposed #2652

@koenkooi

Copy link
Copy Markdown
Contributor

Granted the lack of updates for 3 weeks I've proposed #2652

Since that one has been merged, can this PR be closed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants