| Message ID | 20230920191329.2504837-1-michael.opdenacker@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] contributor-guide/style-guide: Add a note about task idempotence | expand |
On Wed, 2023-09-20 at 21:13 +0200, michael.opdenacker@bootlin.com wrote: > 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 --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 > ===================== FWIW, fine by me, thanks. Richard
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 =====================