From patchwork Thu Jul 14 12:07:43 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tom Rini X-Patchwork-Id: 1656377 X-Patchwork-Delegate: trini@ti.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=konsulko.com header.i=@konsulko.com header.a=rsa-sha256 header.s=google header.b=blh4vbfa; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=85.214.62.61; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4LkCvK13CRz9sB4 for ; Thu, 14 Jul 2022 22:08:45 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 9B5BB84094; Thu, 14 Jul 2022 14:08:16 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com 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; unprotected) header.d=konsulko.com header.i=@konsulko.com header.b="blh4vbfa"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id A202584015; Thu, 14 Jul 2022 14:08:00 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,SPF_PASS, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-qt1-x82a.google.com (mail-qt1-x82a.google.com [IPv6:2607:f8b0:4864:20::82a]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 5250684089 for ; Thu, 14 Jul 2022 14:07:53 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=trini@konsulko.com Received: by mail-qt1-x82a.google.com with SMTP id r17so1206348qtx.6 for ; Thu, 14 Jul 2022 05:07:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=1UL0CnfjUhSibDuFSXRVpTkFq82j5vtnLQxHuDMEy9k=; b=blh4vbfacfYMdoB76XzpR7XuEnwh41SW2EvgxZHx7ARn6TGkiKYFrA4PgG1IHk9B4g 0ZlYkOO43Rcm1J3NpPVZZzEbM4TShvkAOfVopJ84CUzaTn5p39tGOmtc7rjsmzPgyj/W afINIda1ukNv/dGUTXKXlyrJytth+B+TzuDMo= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=1UL0CnfjUhSibDuFSXRVpTkFq82j5vtnLQxHuDMEy9k=; b=KXMFVCGqwInrLtmYjXKFQQhOFWs6JtC23h2z3j1Gfg/2YzMWteQyhS+IdGfaJ1FT/C kwZQ13SADHVXBgOB1L2n758HsnpXKeYvLkQ6luFHnHoJOYJH67F8A6GRMsU0HT2ME2Sx mGNOqUEnKI9u3hibuoudfPPoQxS9rOxofQo/j6lkV/R9kt+Wo8JfgabgDSRuBGAC4ZoZ vty1/96+iSimKFdnIHi6fKhTbQtJJUofriPZiNU/s3IRNJz+BRILJIajntKJCpKqdKQ/ 6BFgPqc5SDPFQu+oTbi2RGv9W+tUsseUPARNKYx0LZx8X9lMk4HxMdd3mD7VVBT+jklS UI3w== X-Gm-Message-State: AJIora+yU8sF+pFZK+XZB37CwUZH/NdZn35hL+YnB7kHYEoe6LbYii1U GlJhCv1zrs1Ym9j1lY35w+A4rIG7LuumOw== X-Google-Smtp-Source: AGRyM1u5ZonEqf471Kr/IPt7OBP4pztFmvGmehLHT3WS9UZjx7F7FP6q5/bvuSgs4zlxtkfyR0YKtQ== X-Received: by 2002:a05:622a:492:b0:31e:b6ac:cf7 with SMTP id p18-20020a05622a049200b0031eb6ac0cf7mr7404879qtx.202.1657800471571; Thu, 14 Jul 2022 05:07:51 -0700 (PDT) Received: from bill-the-cat.lan (cpe-65-184-195-139.ec.res.rr.com. [65.184.195.139]) by smtp.gmail.com with ESMTPSA id y1-20020ac81281000000b0031ea53f4c5esm1209602qti.83.2022.07.14.05.07.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 14 Jul 2022 05:07:50 -0700 (PDT) From: Tom Rini To: u-boot@lists.denx.de Cc: Heinrich Schuchardt Subject: [v3 4/7] doc: Migrate Process wiki page to Sphinx Date: Thu, 14 Jul 2022 08:07:43 -0400 Message-Id: <20220714120746.1137612-4-trini@konsulko.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220714120746.1137612-1-trini@konsulko.com> References: <20220714120746.1137612-1-trini@konsulko.com> MIME-Version: 1.0 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 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. Cc: Heinrich Schuchardt Signed-off-by: Tom Rini --- Changes in v2: - Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich --- doc/develop/index.rst | 1 + doc/develop/process.rst | 200 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 201 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..534da4a2a704 --- /dev/null +++ b/doc/develop/process.rst @@ -0,0 +1,200 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +U-Boot Development Process +========================== + +Management Summary +------------------ + +* Development happens in Release Cycles of 3 months. + +* The first 2 weeks are called Merge Window, which is followed by a + Stabilization Period. + +* Patches with new code get only accepted while the Merge Window is open. + +* 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, even 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 lasts +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 version. + +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 submitted, +but only when somebody (usually the responsible custodian) finds time to do +this. + +In the result, the final version of such patches gets submitted after the +merge window has been closed. + +It is current practice in U-Boot that such patches are eligible to go into the +upcoming release. + +In the result, the release of the ``"-rc1"`` version does not immediately 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 he +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 the Linux Development Process +-------------------------------------------- + +* In Linux, top-level maintainers will collect patches in their trees and 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. + +* 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 most of + the) patches that were submitted during the merge window have been applied. + +Custodians +---------- + +The Custodians take responsibility for some area of the U-Boot code. The +in-tree ``MAINTAINERS`` files list who is reponsible for which areas. + +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 list. + U-Boot has adopted the `Linux kernel signoff policy `_, so the submitter must + include a ``Signed-off-by:`` line. + +#. Everybody who can is invited to review and test the changes. Reviews should + reply on the mailing list with ``Acked-by`` lines. + +#. The responsible custodian + + #. inspects this patch, especially for: + + #. :doc:`codingstyle` + + #. Basic logic: + + * The patch fixes a real problem. + + * The patch does not introduce new problems, especially it does not 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 responsible. + To avoid duplicated efforts, the custodian who starts processing the + 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 include all + sign off/ack lines. + +#. The custodian decides to accept or to reject the patch. + +#. If accepted, the custodian adds the patch to his public git repository 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 + requests that the changes in his public git repository be merged into 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?