diff mbox series

[kirstone,2/9] contributor-guide/style-guide: Add a note about task idempotence

Message ID 20231005200318.2873125-2-michael.opdenacker@bootlin.com
State New
Headers show
Series [kirstone,1/9] contributor-guide/style-guide: Refer to recipes, not packages | expand

Commit Message

Michael Opdenacker Oct. 5, 2023, 8:03 p.m. UTC 
From: Michael Opdenacker <michael.opdenacker@bootlin.com>

From: Richard Purdie <richard.purdie@linuxfoundation.org>

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
CC: Yoann Congal <yoann.congal@smile.fr>

---
Changes in V2:
- Use a bulleted list to clarify the order of steps
  (Suggested by Yoann Congal)
- Recall that we are talking about idempotence in tasks.
  Useful for people overlooking the previous paragraph.
---
 .../contributor-guide/recipe-style-guide.rst       | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
diff mbox series

Patch

diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst
index 1a1c1c6ee2..b63172bd77 100644
--- a/documentation/contributor-guide/recipe-style-guide.rst
+++ b/documentation/contributor-guide/recipe-style-guide.rst
@@ -257,6 +257,20 @@  Tips and Guidelines for Writing Recipes
    and ``-nativesdk`` ones, whenever possible. This avoids having to maintain multiple
    recipe files at the same time.
 
+-  Recipes should have tasks which are idempotent, i.e. that executing a given task
+   multiple times shouldn't change the end result. The build environment is built upon
+   this assumption and breaking it can cause obscure build failures.
+
+-  For idempotence when modifying files in tasks, it is usually best to:
+
+   - copy a file ``X`` to ``X.orig`` (only if it doesn't exist already)
+   - then, copy ``X.orig`` back to ``X``,
+   - and, finally, modify ``X``.
+
+   This ensures if rerun the task always has the same end result and the
+   original file can be preserved to reuse. It also guards against an
+   interrupted build corrupting the file.
+
 Patch Upstream Status
 =====================