From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6011EC43334 for ; Sat, 9 Jul 2022 06:55:57 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 099DF844CF; Sat, 9 Jul 2022 08:55:55 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.b="JdDQUVBJ"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id CAF1B844EB; Sat, 9 Jul 2022 08:55:53 +0200 (CEST) Received: from mout.gmx.net (mout.gmx.net [212.227.17.20]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 9A795805FE for ; Sat, 9 Jul 2022 08:55:50 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1657349749; bh=Ad54E1HmzJ0q0wJaTbePTiPeJ0X/eHJSG9h4wiLCjv0=; h=X-UI-Sender-Class:Date:Subject:To:References:From:Cc:In-Reply-To; b=JdDQUVBJJEKhh6Ugx6gHcWHS7/9uq/+lSZMp4S2Ex+gWoxVBrrrCkiY+rXfj8TjHA 42T0Pg7dL3aX7ierv6BH63bMgCdZOX3K+C8ljgqxu9qpGZj6wNyOcZX31d7w7h2slu OihBDj7GjvFHnsBVpQoG8Kj4GKt4kdgYy03n+Sl8= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [192.168.123.94] ([62.143.94.109]) by mail.gmx.net (mrgmx105 [212.227.17.168]) with ESMTPSA (Nemesis) id 1MkYbu-1njE8g3jTC-00m4nV; Sat, 09 Jul 2022 08:55:48 +0200 Message-ID: <2b600d2f-1534-062e-f8b0-ba65676fdfcc@gmx.de> Date: Sat, 9 Jul 2022 08:55:48 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.0.1 Subject: Re: [PATCH 4/4] doc: Migrate Process wiki page to sphinx Content-Language: en-US To: Tom Rini References: <20220627171722.1153337-1-trini@konsulko.com> <20220627171722.1153337-5-trini@konsulko.com> From: Heinrich Schuchardt Cc: u-boot@lists.denx.de, Simon Glass In-Reply-To: <20220627171722.1153337-5-trini@konsulko.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:hZbtMK5uXx2cfC9JwfotBrr5Iy6keIRsvz1kRhICWDomGY0goTG T+9F+duUCb555KBl1pPeBxWZ6pURHkSO62IwoScXQdlsbfGoQNhsuBAJXwQkeU9qqxbBuiR Nxygz/XubdB9SrOz6qUvtqimabLTvJ8lRySsNixD9kyeCvBDoKlvuR7IUDV577mJWIs2TjF GvpnQA7t3r7P1YqTHmRWg== X-UI-Out-Filterresults: notjunk:1;V03:K0:2EzcPHrHWHg=:vAYUDpEpUOWxxSfoS8YXjE 3ai2N4qmzSsx1KJQRC2CeoErm2OfCQPSkwFHT6TZGE2pHh1hkm6IrGJ2wIz1Jt1FMcL9NYVx3 1LhpWV/f+NuIL1sMS2OvnBAZm3O3eMucDAcWs45iPb5hDzxGJorQJp9Vyg1E9bpvfuE6EVKOs 8cgum0LDgNWrs7f1yP8PT7DNIY6KiPfp6td+F/x8AVOlwxThRaWotdtTXE8xqAu6SQwLy6Ukq fu5ThJ2nv3uUCPeOvY2ou4ftIIBTRmKoaa411XrkwhgBtP8Xe3jWqBPcp6QovnhKN526FM1xQ vfUAIGGy0gdzbHZGkpYlCJOSEMivnXLHmQ3yInPf+d2IgYjE6e9F3GcFw5UGl7K8o/EJKf/gv SEHtVhs9QcQyePXmi2I8Da+sgAzdnAWkkm7NZt4eRN8MNNdPrRR2ZWxq98tl+2Ou+Y9L7igPw nWb+HSHOybgG0xSNOoBTpLPwcFBzZ9ekIfaVIVMOq7Q4s/hXSJQmP8dxYwj527YusmJQ9t8m1 F28a/7/kVn8/nfVrhppLk5oGJrPKO0JorEuj1uQWNxpIwjFajN5Hc9/J9cBTkJgnxfTjxZJMq EdpzpRNYFPC1+BR64xHwqsYxHrgXNk2dOJazHpYgfNejEp8K+EUN3K4p4WWyFJmpJumMlYHG3 jnz3W0JqGPGH5FL5WNQbU4e8SQ6yljSBnfHj5ku/esMTQfywkn3Z0MhlfTd9krPBNqs3c3wwz /5ms5wQyvDaajT3IjocI7/6No8f+MxY2glWIncICNUPkaHK5VrTL0U8fgrI5OyuwST28DM2GC +HM8+ydLo3wXVbeeSwyMBsy+5kOzlPXk5YVWcGhcRY3PIO4zwtC+A1/dlZ4nTzjH4y0Fr1Uha q9QxuSxNnqzJsIf6TOCw4Akt3TnGmqy66uNNoziuYBsnz5bR1A7um6N8sDc8xGe7BspzPSjG5 EZRAePJ1HuniBkysheCGoyKj40CGwPlVjF4skiLKJN9oF3sLubPHVmy80mVQE7pgBwHLs0fx1 ACL3sHJ+2iEWyUV5M0YhGUrQT5FFgN1r1UZBFhswSSGU7UVSlLha0n9YfAXcDEiVdZI6/1q0V eDDAbBnb5citEq9lKOSDav/0wfjVVKDJJh7lxxF+ngiEE0VEAO5k0kjbw== X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean On 6/27/22 19:17, Tom Rini wrote: > Move the current Process wiki page to doc/develop/process.rst. The > changes here are for formatting or slight rewording so that it reads > well when linking to other sphinx documents. > > Signed-off-by: Tom Rini > --- > doc/develop/index.rst | 1 + > doc/develop/process.rst | 182 ++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 183 insertions(+) > create mode 100644 doc/develop/process.rst > > diff --git a/doc/develop/index.rst b/doc/develop/index.rst > index c0f4f0ba413a..eab00a55382a 100644 > --- a/doc/develop/index.rst > +++ b/doc/develop/index.rst > @@ -11,6 +11,7 @@ General > > codingstyle > designprinciples > + process > > Implementation > -------------- > diff --git a/doc/develop/process.rst b/doc/develop/process.rst > new file mode 100644 > index 000000000000..dd279fb9eff1 > --- /dev/null > +++ b/doc/develop/process.rst > @@ -0,0 +1,182 @@ > +.. SPDX-License-Identifier: GPL-2.0+: > + > +U-Boot Development Process > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D > + > +Management Summary > +------------------ > + > +* Development happens in Release Cycles of 3 months. Do we need all this capitalization? > +* The first 2 weeks are called Merge Window, which is followed by a > + Stabilization Period. Please, separate bullets by blank lines. > +* Patches with new code get only accepted while the Merge Window is ope= n. > +* A patch that is generally in good shape and that was submitted while = the > + Merge Window was open is eligible to go into the upcoming release, ev= en if > + changes and resubmits are needed. > +* During the Stabilization Period, only patches that contain bug fixes = get > + applied. > + > +Phases of the Development Process > +--------------------------------- > + > +U-Boot development takes place in `Release Cycles > +`_. A Release Cycle last= s > +normally for three months. > + > +The first two weeks of each Release Cycle are called *Merge Window*. > + > +It is followed by a *Stabilization Period*. > + > +The end of a Release Cycle is marked by the release of a new U-Boot ver= sion. Don't repeat yourself. > + > +Merge Window > +------------ > + > +The Merge Window is the period when new patches get submitted > +(and hopefully accepted) for inclusion into U-Boot mainline. > + > +This is the only time when new code (like support for new processors or= new > +boards, or other new features or reorganization of code) is accepted. > + > +Twilight Time > +------------- > + > +Usually patches do not get accepted as they are - the peer review that = takes > +place will usually require changes and resubmits of the patches before = they > +are considered to be ripe for inclusion into mainline. > + > +Also, the review often happens not immediately after a patch was submit= ted, > +but only when somebody (usually the responsible custodian) finds time t= o do > +this. > + > +In the result, the final version of such patches gets submitted after t= he > +merge window has been closed. > + > +It is current practice in U-Boot that such patches are eligible to go i= nto the > +upcoming release. > + > +In the result, the release of the ``"-rc1"`` version does not immediate= ly follow > +the closing of the Merge Window. > + > +Stabilization Period > +-------------------- > + > +During the Stabilization Period only patches containing bug fixes get > +applied. > + > +Corner Cases > +------------ > + > +Sometimes it is not clear if a patch contains a bug fix or not. > +For example, changes that remove dead code, unused macros etc. or > +that contain Coding Style fixes are not strict bug fixes. > + > +In such situations it is up to the responsible custodian to decide if h= e > +applies such patches even when the Merge Window is closed. > + > +Exception: at the end of the Stabilization Period only strict bug > +fixes my be applied. > + > +Sometimes patches miss the the Merge Window slightly - say by few > +hours or even a day. Patch acceptance is not as critical as a > +financial transaction, or such. So if there is such a slight delay, > +the custodian is free to turn a blind eye and accept it anyway. The > +idea of the development process is to make it foreseeable, > +but not to slow down development. > + > +It makes more sense if an engineer spends another day on testing and > +cleanup and submits the patch a couple of hours late, instead of > +submitting a green patch which will waste efforts from several people > +during several rounds of review and reposts. > + > +Differences to Linux Development Process > +---------------------------------------- %s/to/to the/ > + > +* In Linux, top-level maintainers will collect patches in their trees a= nd send > + pull requests to Linus as soon as the merge window opens. > + So far, most U-Boot custodians do not work like that; they send pull = requests > + only at (or even after) the end of the merge window. %s/$/\n/ > +* In Linux, the closing of the merge window is marked by the release of= the > + next ``"-rc1"`` > + In U-Boot, ``"-rc1"`` will only be released after all (or at least mo= st of > + the) patches that were submitted during the merge window have been ap= plied. > + > +Custodians > +---------- > + > +The Custodians take responsibility for some area of the U-Boot code. T= he > +in-tree ``MAINTAINERS`` files list who is reponsible for which areas. %/reponsible/responsible/ > + > +It is their responsibility to pick up patches from the mailing list > +that fall into their responsibility, and to process these. > + > +A very important responsibility of each custodian is to provide > +feedback to the submitter of a patch about what is going on: if the > +patch was accepted, or if it was rejected (which exact list of > +reasons), if it needs to be reworked (with respective review > +comments). Even a "I have no time now, will look into it later" > +message is better than nothing. Also, if there are remarks to a > +patch, these should leave no doubt if they were just comments and the > +patch will be accepted anyway, or if the patch should be > +reworked/resubmitted, or if it was rejected. > + > +Work flow of a Custodian > +------------------------ > + > +The normal flow of work in the U-Boot development process will look > +like this: > + > +#. A developer submits a patch via e-mail to the u-boot-users mailing l= ist. > + U-Boot has adopted the `Linux kernel signoff policy `_, so the submitter mu= st > + include a ``Signed-off-by:`` line. Keep lines at 80 characters. > +#. Everybody who can is invited to review and test the changes. Review= s should > + reply on the mailing list with ``Acked-by`` lines. %s/Acked-by/Reviewed-by/ ? Please, refer to https://www.kernel.org/doc/html/v4.17/process/submitting-patches.html for the usage of Reviewed-by and Acked-by. > +#. The responsible custodian > + > + #. inspects this patch, especially for: This should not be a bullet but go into the line above. > + > + #. :doc:`codingstyle` > + #. Basic logic: > + > + * The patch fixes a real problem. > + * The patch does not introduce new problems, especially it does n= ot break > + other boards or architectures > + > + #. U-Boot Philosophy > + #. Applies cleanly to the source tree > + #. passes a ``MAKEALL`` compile test without creating new warnings > + > +#. Notes: > + > + #. In some cases more than one custodian may be affected or feel resp= onsible. > + To avoid duplicated efforts, the custodian who starts processing t= he > + patch should send a short ACK to the mailing list. > + #. We should create some tool to automatically do this. > + #. This is well documented in :doc:`designprinciples`. > + #. The custodian decides himself how recent the code must be. It is > + acceptable to request patches against the last officially released > + version of U-Boot or newer. Of course a custodian can also accept > + patches against older code. > + #. Commits should show original author in the ``author`` field and in= clude all > + sign off/ack lines. > + > +5. The custodian decides to accept or to reject the patch. Don't mix # bullets and numbers. > +#. If accepted, the custodian adds the patch to his public git reposito= ry and > + notifies the mailing list. This note should include: > + > + * a short description of the changes > + * the list of the affected boards / architectures etc. > + * suggested tests > + > + Although the custodian is supposed to perform his own tests > + it is a well-known and accepted fact that he needs help from > + other developers who - for example - have access to the required > + hardware or tool chains. > + The custodian request help for tests and feedback from > + specific maintainers and U-Boot users. > +#. Once tests are passed, some agreed time limit expires, the custodian No clue what agreed time limit you are referring to. The custodian will create a merge request when the merge window matching the type of the patch (feature or bug) is open. > + requests that the changes in his public git repository be merged int= o the > + main tree. If necessary, the custodian may have to adapt his changes= to > + allow for a clean merge. > + Todo: define a reasonable time limit. 3 weeks? This todo-line is not helpful. If the patch contains a new feature, the custodian has to wait for the next merge window before issuing a pull request for it. > + Please, avoid empty lines at the end of file. Best regards Heinrich