Re: [PATCH] Add an initial CONTRIBUTE.rst

[Tom Rini <trini@konsulko.com>]

[-- Attachment #1: Type: text/plain, Size: 6072 bytes --]

On Thu, Mar 05, 2026 at 06:45:33PM +0100, Quentin Schulz wrote:
> Hi Peter,
> 
> On 3/3/26 10:46 PM, Peter Robinson wrote:
> > Add a contributors file to provide a high level overview
> > for people who wish to contribute to the project outlining
> > basic details and setting some project expectations.
> > 
> > This isn't intended to replace any of the existing documentation
> > but rather provide a succinct top level document that's easy
> > to find to enable users to understand the project and get
> > started as quickly as possible.
> > 
> > Signed-off-by: Peter Robinson <pbrobinson@gmail.com>
> > Cc: Tom Rini <trini@konsulko.com>
> > Cc: Neil Armstrong <neil.armstrong@linaro.org>
> > ---
> >   doc/CONTRIBUTE.rst | 70 ++++++++++++++++++++++++++++++++++++++++++++++
> >   doc/index.rst      | 10 +++++++
> >   2 files changed, 80 insertions(+)
> >   create mode 100644 doc/CONTRIBUTE.rst
> > 
> > diff --git a/doc/CONTRIBUTE.rst b/doc/CONTRIBUTE.rst
> > new file mode 100644
> > index 00000000000..7602e5c5a6a
> > --- /dev/null
> > +++ b/doc/CONTRIBUTE.rst
> > @@ -0,0 +1,70 @@
> > +.. SPDX-License-Identifier: GPL-2.0+
> > +.. sectionauthor:: Peter Robinson <pbrobinson@gmail.com>
> > +
> > +Overview
> > +--------
> > +
> > +This document is a high level contributors overview setting overall expectations,
> > +so people can get started quickly, the rest of the documentation goes into the
> > +details.
> > +
> > +Code of Conduct
> > +---------------
> > +
> > +The U-Boot project doesn't currently have an explicit code of conduct, but all
> > +contributors are expected to act cordially to, and be respectful of, each others
> 
> s/others/other's/ ?
> 
> > +contributions and opinions. There are many code of conducts for open source
> > +projects available to review if you are unsure of expectations.
> > +
> > +Repository
> > +----------
> > +
> > +The official U-Boot repository is located at https://source.denx.de/u-boot/u-boot
> > +> +Contributions
> > +-------------
> > +
> > +Contributions to the project are welcome. The U-Boot project uses a fairly
> > +traditional Linux style development workflow using git and `a mailing list
> > +<https://lists.denx.de/listinfo/u-boot>`_.
> 
> Note that lore.kernel.org/u-boot may be more user-friendly (especially for
> people using b4).

Yes, but that's the official list location, lore is a mirror. And...

> > +Patches should be sent to the mailing list using ``git send-email`` or the
> > +equivilant commands using ``b4`` or ``patman`` with appropriate sign-off and
> > +attributions for the code in question. Maintainers should be copied on mails
> > +and they can be found with the ``./scripts/get_maintainer.pl 0001-fix.patch``
> > +script. Please don't send patches as attchments, and ensure corporate mail
> 
> s/attchments/attachments/
> 
> > +systems don't reformat patches, append disclaimers or other uneccessary notes.
> 
> s/uneccessary/unnecessary/
> 
> > +
> > +Patch Series
> > +------------
> > +
> > +Patch series for a specific subject are welcome but they should be constrained
> > +to a single topic with a cover letter outlining the intention of the series.
> > +
> > +Generally bug fixes for existing bugs should be at the beginning of the
> > +series before any enhancements to allow those patches to be picked up early.
> > +
> > +Each iteration of a patch set should be versioned, allow enough time for people
> 
> Awkward wording here. Maybe switch to a dot instead of a comma?
> 
> > +to review previous versions of the series and incorporate all the review
> > +feedback before sending a new version. A week between larger patch sets is
> > +considered as reasonable amount of time.
> > +
> > +Development Branches
> > +--------------------
> > +
> > +The U-Boot developers use two main branches for developing the code. The master
> > +branch is used for the current development cycle, while there is also a next
> > +branch intended to land changes for the next release early to enable wider
> > +testing of larger code changes. The next branch is merged to master shortly
> > +after the tagging of a new major release.
> > +
> > +Similar to Linux there is a two week merge window post release after which a
> > +release candidate is tagged. There's typically a new release candidate every
> > +two weeks post merge window until the stable generally available release.
> > +
> > +Release Schedule
> > +----------------
> > +
> > +There is currently four major releases a year in January (.01), April (.04),
> > +July (.07) and October (.10). These typically happen on the first Tuesday of
> > +that month. There is currently no release branches or long term releases.
> 
> General remark, this doesn't provide links to more extensive documentation
> so it feels a bit like a single-source of truth. We may also unwittingly end
> up contradicting ourselves in other parts of the docs.
> 
> So at the very least can we have links in this docs pointing to the more
> extensive documentation? Especially on the mailing list contribution
> workflow.
> 
> Another option could be to reuse verbatim other portions of the docs. Move
> current snippets into my-snippet.rst.inc and then in the appropriate places
> do
> 
> .. include:: my-snippet.rst.inc
> 
> Such that it cannot be outdated. Of course, wording or syntax may need to be
> adapted so it's not looking odd in the various places this may be included.

I think we need to have this document be a bit more referential of the
other documents we have. I think the snippet part might get difficult to
word on its own so perhaps more of a style of super brief overview and
link to the full doc. Like for the release schedule just something about
how we have 4 releases per year (typically January, April, July and
October) and their schedule is well defined in advance. For more details
please see :rst-link to doc/develop/release_cycle.rst with appropriate
link text:.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]