Maintaining patches in a Yocto Project environment requires a disciplined workflow.
Because Yocto-based systems often rely on version-pinned, cross-compiled, and hardware-specific sources, every patch must be traceable, maintainable, and clearly classified.

The Upstream-Status tag exists to describe how each patch relates to the upstream project, helping developers understand whether a patch is temporary, local, permanent, or already integrated upstream.

This article explains the purpose of the tag and provides detailed guidelines for choosing the correct value.

#What is Upstream-Status?

Upstream-Status is a metadata tag included in Yocto patch headers.
It describes the patch’s relationship to the upstream source (Linux kernel, U-Boot, system libraries, utilities, etc.).

Yocto introduces this tag to help maintainers:

• Track whether patches should be upstreamed
• Identify patches that can be removed after source upgrades
• Reduce rebase and forward-porting effort
• Separate BSP-specific code from generic fixes
• Avoid duplicated or obsolete patches

A properly classified patch significantly improves BSP maintainability.

#Why It Matters

Correct Upstream-Status values:

• Make Yocto upgrades smoother
• Prevent patch duplication
• Reduce merge conflicts
• Communicate patch intentions clearly to other developers
• Ensure that improvements make their way into the broader ecosystem

Good patch hygiene is essential for long-term embedded Linux maintenance.

Valid Upstream-Status Values

Below is a complete overview of all commonly used and accepted values.

#Upstream-Status: Accepted

Meaning:
The patch has already been merged upstream.

Use when:

• Upstream has accepted your patch.
• Yocto still uses an older version that needs the patch manually.

Example:

 1Upstream-Status: Accepted [commit abc1234de]

#Upstream-Status: Backport

Meaning:
The patch exists upstream; you are backporting it into an older version used by Yocto.

Use when:

• Upstream includes the fix.
• Your BSP uses an older version of the kernel/U-Boot/recipe.

Example:

 1Upstream-Status: Backport [from commit 8fc992c]

#Upstream-Status: Inappropriate

Meaning:
The patch will never be accepted upstream because it is specific to your hardware or product.

Typical cases:

• Board-specific device tree modifications
• Proprietary or NDA-protected code
• Custom product logic
• Temporary platform hacks

Example:

 1Upstream-Status: Inappropriate [board-specific]

#Upstream-Status: Denied

Meaning:
You submitted the patch upstream, but it was rejected.

Use when:

• Maintainers explicitly refuse your change.
• You still require the patch internally.

Example:

 1Upstream-Status: Denied [reason: violates subsystem design]

#Upstream-Status: Pending

Meaning:
Patch was submitted and is currently under active review.

Use when:

• Patch is on a mailing list.
• Maintainers are reviewing or discussing it.

Example:

 1Upstream-Status: Pending [sent to linux-leds on 2025-11-27]

#Upstream-Status: Submitted

Meaning:
Patch has been submitted upstream, but no review has yet happened.

Difference to Pending:

• Submitted = you sent it
• Pending = reviewers are actively processing it

Example:

 1Upstream-Status: Submitted [linux-arm-kernel, msg-id <1234@domain>]

#Upstream-Status: Submitted [Not-Accepted]

Meaning:
Patch was submitted but is known to be unacceptable upstream.

Use when:

• Maintainers indicate it won't be accepted.

Example:

 1Upstream-Status: Submitted [won't be accepted: platform-specific hack]

#Upstream-Status: Unknown (avoid if possible)

Meaning:
Upstream situation is unknown.

Use when:

• Temporarily during classification.
• Not acceptable for production BSPs.

Example:

 1Upstream-Status: Unknown

Choosing the Correct Tag

Best Practices for Yocto Patch Management

#✔ Always include metadata

 1Upstream-Status: <value>
 2Signed-off-by: Your Name <email>

#✔ Document commit IDs

 1Upstream-Status: Backport [from commit 3ab455e]

#✔ Explain why a patch is Inappropriate or Denied

Helps future maintainers avoid confusion.

#✔ Re-evaluate patches during upgrades

During kernel/U-Boot bumps:

• Remove Accepted and Backport patches
• Check if Pending patches were accepted
• Clean up temporary patches

Example Complete Patch Header

 1From: Martin Mitkov <mail@mitkov-systems.de>
 2Subject: [PATCH] status: patches: Fix yocto patch status handling
 3
 4Upstream-Status: Pending [sent to linux-leds 2025-11-27]
 5Signed-off-by: Martin Mitkov <mail@mitkov-systems.de>

Conclusion

Using Upstream-Status correctly ensures that your Yocto BSP remains clean, stable, and maintainable.
Proper classification:

• Reduces rebase effort
• Improves collaboration
• Makes patch origins transparent
• Keeps your layer future-proof

A disciplined patch workflow is key to long-term embedded Linux success.