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 <[email protected]>
Reviewed-by: Ahmad Fatoum <[email protected]> > --- > 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 |
