mail archive of the barebox mailing list
 help / color / mirror / Atom feed
* [PATCH] Documentation: Officially accept GitHub pull requests
@ 2026-09-02  8:23 Sascha Hauer
  2026-09-02  8:41 ` Ahmad Fatoum
  0 siblings, 1 reply; 2+ messages in thread
From: Sascha Hauer @ 2026-09-02  8:23 UTC (permalink / raw)
  To: Barebox List

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>
---
 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.
-- 
2.47.3




^ permalink raw reply	[flat|nested] 2+ messages in thread
end of thread, other threads:[~2026-09-02  8:42 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-09-02  8:23 [PATCH] Documentation: Officially accept GitHub pull requests Sascha Hauer
2026-09-02  8:41 ` Ahmad Fatoum

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox