ref-manual/faq: Add entry about github pull requests

This is an emotive topic but try and fairly document some of the pros and cons
of such a model and where they make sense along with why the project has made
the decisions it currently has.

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/faq.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

Hi Richard,

On 11/2/26 12:08 PM, Richard Purdie via docs wrote:
> This is an emotive topic but try and fairly document some of the pros and cons
> of such a model and where they make sense along with why the project has made
> the decisions it currently has.
> 
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>   documentation/ref-manual/faq.rst | 28 ++++++++++++++++++++++++++++
>   1 file changed, 28 insertions(+)
> 
> diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
> index c1657d677..60e89d834 100644
> --- a/documentation/ref-manual/faq.rst
> +++ b/documentation/ref-manual/faq.rst
> @@ -108,6 +108,34 @@ It is very easy to check whether a patch has merged by looking at the repository
>   pulling and rebasing.
>   
>   
> +Why doesn't the project use github?
> +-----------------------------------
> +

s/github/GitHub/ for the whole patch.

> +This is not a simple question and there is no right answer to it but there is some
> +background worth appreciating.
> +
> +Some components within the project do accept pull requests from github, others don't.
> +The README in the component in question should make the process clear for that
> +component. Github itself is a commercial operation and there are concerns about what
> +happens if they change direction or decide to to discontinue it as there is precedent in
> +the past for that kind of thing happening. Equally, there are open alternatives to it.
> +
> +The bigger issue is the model. Mailing lists allow for wide peer review. The people
> +performing that review are extremely valuable with experience built up over decades.
> +The github model doesn't really lend itself to them being able to easily see or be
> +aware of changes beyond the maintainer accepting the pull request. That model also

There's a CODEOWNERS file "standard" to specify those (free tier GitHub; 
paid tier GitLab) who should be reviewers of some files in the project. 
However, this is akin to having a MAINTAINERS file like in U-Boot and 
Linux kernel when using the mailing list contribution with 
get_maintainer.pl script, which the project doesn't want to be using, so 
this doesn't apply. Just wanted it to be mentioned at list on the 
mailing list as part of review because I have a suspicion this might be 
raised in the future.

> +tends to focus on the single maintainer with total authority, which for components
> +like OE-Core, simply isn't how things operate for us. Moving to much a model would
> +alienate our existing reviewers and our community consensus approach to changes.
> +

Can I suggest adding something like:

"""
Another issue is that GitHub and similar forges use the Pull Request 
mechanism, heavily leaning into reviewing and testing the Pull Request 
as a whole (e.g. the CI only runs on the last commit of the Pull 
Request, and per-commit reviews are painful to write and follow-up on). 
Using GitHub or a similar forge would require the project to completely 
change its reviewing process (or have two, wildly different, if we were 
to allow both mailing list and Pull Request-like contributions).
"""

as another pain point for using common forges?

Cheers,
Quentin

Hi Richard,

I don’t have any content-related feedback and only noticed a few typos.

On Mon, Nov 02 2026 at 11:08 +0000, "Richard Purdie via docs" <richard.purdie=linuxfoundation.org@lists.yoctoproject.org> wrote:
> This is an emotive topic but try and fairly document some of the pros and cons
> of such a model and where they make sense along with why the project has made
> the decisions it currently has.
>
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>  documentation/ref-manual/faq.rst | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
>
> diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
> index c1657d677..60e89d834 100644
> --- a/documentation/ref-manual/faq.rst
> +++ b/documentation/ref-manual/faq.rst
> @@ -108,6 +108,34 @@ It is very easy to check whether a patch has merged by looking at the repository
>  pulling and rebasing.
>  
>  
> +Why doesn't the project use github?
> +-----------------------------------
> +
> +This is not a simple question and there is no right answer to it but there is some
> +background worth appreciating.
> +
> +Some components within the project do accept pull requests from github, others don't.
> +The README in the component in question should make the process clear for that
> +component. Github itself is a commercial operation and there are concerns about what
> +happens if they change direction or decide to to discontinue it as there is precedent in

s/to to/to/

> +the past for that kind of thing happening. Equally, there are open alternatives to it.
> +
> +The bigger issue is the model. Mailing lists allow for wide peer review. The people
> +performing that review are extremely valuable with experience built up over decades.
> +The github model doesn't really lend itself to them being able to easily see or be
> +aware of changes beyond the maintainer accepting the pull request. That model also
> +tends to focus on the single maintainer with total authority, which for components
> +like OE-Core, simply isn't how things operate for us. Moving to much a model would

s/Moving to much a model/Moving to such a model/

Best regards,
Ulrich


> +alienate our existing reviewers and our community consensus approach to changes.
> +
> +So yes, for a contributor wanting to make a quick submission, github and similar models
> +are attractive, but they would likely come at a cost to the project's long term health.
> +They can work well for the single or limited number of maintainer model, and for components
> +with the setup, but not for other areas which benefit from wide peer review. We live
> +in hope that tools can catch up with that, we'd even love to develop them ourselves if
> +we had time but sadly, we don't at this point.
> +
> +
>  Building environment
>  ====================
>  
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#10758): https://lists.yoctoproject.org/g/docs/message/10758
> Mute This Topic: https://lists.yoctoproject.org/mt/122055611/3618626
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [u.oelmann@pengutronix.de]
> -=-=-=-=-=-=-=-=-=-=-=-