Re: [PATCH] Documentation: Officially accept GitHub pull requests

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

On 9/2/26 10:23 AM, Sascha Hauer wrote:
> barebox is on GitHub for years already and we occasionally merged GitHub
> merge requests, but this was always the exception. This changes now:
> We now officially accept GitHub merge requests.
> 
> Adjust the documentation accordingly. While at it better explain the
> patchflow into barebox to justify why work should be done on master
> while being targeted for next. Also mention the exceptions to this
> rule and how merge conflicts are handled.
> 
> Assisted-by: Claude:claude-opus-5
> Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

Reviewed-by: Ahmad Fatoum <a.fatoum@pengutronix.de>

> ---
>  Documentation/devel/contributing.rst | 13 +++++-
>  Documentation/devel/devel.rst        |  1 +
>  Documentation/devel/patch-flow.rst   | 62 ++++++++++++++++++++++++++++
>  README.rst                           |  7 ++--
>  4 files changed, 79 insertions(+), 4 deletions(-)
>  create mode 100644 Documentation/devel/patch-flow.rst
> 
> diff --git a/Documentation/devel/contributing.rst b/Documentation/devel/contributing.rst
> index 8b92c6f483..d62d6de361 100644
> --- a/Documentation/devel/contributing.rst
> +++ b/Documentation/devel/contributing.rst
> @@ -47,7 +47,9 @@ Patch series can be sent and fetched from the list using `b4 <https://pypi.org/p
>  
>     b4 shazam -M https://lore.barebox.org/$messageid # replace with link
>  
> -Fixes should apply on master and new features on the next branch.
> +Base your work on ``master``. Fixes are applied there directly, new features
> +go to ``next`` first. See :ref:`patch_flow` for the branches involved and
> +what happens to a patch after it has been picked up from the list.
>  
>  If a series fails to apply, ``b4`` can determine/guess the base
>  and have ``FETCH_HEAD`` point at it::
> @@ -65,6 +67,15 @@ patches can be sent with::
>  
>  See the `b4 documentation <https://b4.docs.kernel.org/en/latest/>`_ for details.
>  
> +GitHub Pull Requests
> +--------------------
> +
> +Besides the mailing list, contributions are also accepted as pull requests
> +against `the project on GitHub <https://github.com/barebox/barebox>`_. The
> +same rules apply: base your work on ``master`` and target the pull request
> +at ``next``, so that GitHub can detect when it has been applied. See
> +:ref:`patch_flow` for details.
> +
>  Continuous Integration
>  ----------------------
>  
> diff --git a/Documentation/devel/devel.rst b/Documentation/devel/devel.rst
> index 810b5d254e..8a92d864af 100644
> --- a/Documentation/devel/devel.rst
> +++ b/Documentation/devel/devel.rst
> @@ -10,6 +10,7 @@ Contents:
>  
>     architecture
>     contributing
> +   patch-flow
>     porting
>     troubleshooting
>     filesystems
> diff --git a/Documentation/devel/patch-flow.rst b/Documentation/devel/patch-flow.rst
> new file mode 100644
> index 0000000000..5145e6c32f
> --- /dev/null
> +++ b/Documentation/devel/patch-flow.rst
> @@ -0,0 +1,62 @@
> +.. _patch_flow:
> +
> +Patch Flow
> +==========
> +
> +This document describes the path a patch takes from the mailing list into a
> +barebox release. See :ref:`contributing` for how to prepare and submit the
> +patch in the first place.
> +
> +Branches
> +--------
> +
> +Two branches are published in the official barebox repositories:
> +
> +``master``
> +  The stable mainline. Releases are branched from here. ``master`` is
> +  fast-forward only and never rewritten, so it is safe to base work on.
> +
> +``next``
> +  The integration branch. It contains everything queued for the next
> +  release. ``next`` is **not** fast-forward: it is regularly rebuilt from
> +  scratch and force-pushed. Never base work on ``next`` that you intend to
> +  keep, and never merge ``next`` into a downstream branch. Internally all
> +  new features are collected in ``for-next/`` branches from which ``next``
> +  is merged
> +
> +From patch to release
> +---------------------
> +
> +#. A patch is picked up from the mailing list and applied to the
> +   ``for-next/`` topic branch matching its subsystem or topic.
> +
> +#. ``next`` is rebuilt by merging all internal ``for-next/`` branches on top
> +   of ``master``, and is published for testing and CI.
> +
> +#. After the release, the ``for-next/`` branches are merged into ``master``
> +   and deleted. ``next`` is then rebuilt on the new ``master``, and the cycle
> +   starts over.
> +
> +The consequence for contributors is that a new feature takes one to two
> +months to reach a release, depending on where in the cycle it was applied,
> +while a fix can make the next release. The monthly release schedule and the
> +release numbering are described in the "Release Strategy" section of the
> +top-level ``README.rst``.
> +
> +What to base your work on
> +-------------------------
> +
> +New features should be based on ``master`` and targeted for ``next``. Merge
> +conflicts like Makefile/Kconfig conflicts or context changes will be handled
> +at the maintainers side. If and only if a patch depends on a feature currently
> +sitting in ``next`` please base your work on ``next`` and note explicitly when
> +sending the patch.
> +
> +GitHub pull requests
> +--------------------
> +
> +We also accept GitHub pull requests. Same rules as above apply. Make sure your
> +work is based on master and the pull request is targeted for ``next`` which
> +lets the GitHub Logic properly detect when a pull request is applied. Should
> +you have to base your work on ``next`` for the above reasons your changes will
> +be cherry picked and the pull request is manually closed.
> diff --git a/README.rst b/README.rst
> index 71286904a8..fe783028df 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -256,9 +256,10 @@ are the release rules:
>    to get patches in on a very short time scale (usually a month at most).
>  
>  - New features are applied to the ``next`` branch. Fixes directly to the
> -  ``master`` branch. Releases are always branched from ``master`` and then
> -  ``next`` is merged into ``master``. Thus new features take 1-2 months
> -  until they hit a release.
> +  ``master`` branch. Releases are always branched from ``master``, and only
> +  afterwards is the material queued in ``next`` merged into ``master``. Thus
> +  new features take 1-2 months until they hit a release. See
> +  ``Documentation/devel/patch-flow.rst`` for the details.
>  
>  - Usually, there are no bugfix releases, so z=0. If there is a need
>    to make a bugfix release, z is the right place to increment.

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |