[PATCH v2 1/9] conf.py: Add oe_git directive

[PATCH v2 1/9] conf.py: Add oe_git directive

[Paul Barker]

This simplifies linking to git repositories on openembedded.org.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 documentation/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/documentation/conf.py b/documentation/conf.py
index a8df6e8f8..96118abec 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -78,6 +78,7 @@ extlinks = {
     'yocto_git': ('https://git.yoctoproject.org%s', None),
     'oe_home': ('https://www.openembedded.org%s', None),
     'oe_lists': ('https://lists.openembedded.org%s', None),
+    'oe_git': ('https://git.openembedded.org%s', None),
 }
 
 # Intersphinx config to use cross reference with Bitbake user manual
-- 
2.20.1

[PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

After discussions on IRC with Ross we concluded that the `ross/mut`
branch shouldn't really be listed in the docs as it's more of a personal
test branch. Instead we should list the -next branches for
openembedded-core and poky.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
 1 file changed, 21 insertions(+), 12 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 27aacde60..6f526c203 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
 section in the Yocto Project Overview and Concepts Manual for additional
 concepts on working in the Yocto Project development environment.
 
-Two commonly used testing repositories exist for OpenEmbedded-Core:
-
--  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
-   ``poky-contrib`` repository in the
-   :yocto_git:`Yocto Project source repositories <>`.
-
--  *"master-next" branch:* This branch is part of the main "poky"
-   repository in the Yocto Project source repositories.
-
-Maintainers use these branches to test submissions prior to merging
-patches. Thus, you can get an idea of the status of a patch based on
-whether the patch has been merged into one of these branches.
+Maintainers commonly use ``-next`` branches to test submissions prior to
+merging patches. Thus, you can get an idea of the status of a patch based on
+whether the patch has been merged into one of these branches. The commonly
+used testing branches for OpenEmbedded-Core are as follows:
+
+-  *openembedded-core "master-next" branch:* This branch is part of the
+   :oe_git:`openembedded-core </openembedded-core/>` repository contains
+   proposed changes to the core metadata.
+
+-  *poky "master-next" branch:* This branch is part of the
+   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
+   changes to bitbake, the core metadata and the poky distro.
+
+Similarly, stable branches maintained by the project may have corresponding
+``-next`` branches which collect proposed changes. For example,
+``dunfell-next`` and ``gatesgarth-next`` branches in both the
+"openembdedded-core" and "poky" repositories.
+
+Other layers may have similar testing branches but there is no formal
+requirement or standard for these so please check the documentation for the
+layers you are contributing to.
 
 .. note::
 
-- 
2.20.1

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Nicolas Dechesne]

On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
>
> After discussions on IRC with Ross we concluded that the `ross/mut`
> branch shouldn't really be listed in the docs as it's more of a personal
> test branch. Instead we should list the -next branches for
> openembedded-core and poky.
>
> Signed-off-by: Paul Barker <pbarker@konsulko.com>
> ---
>  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
>  1 file changed, 21 insertions(+), 12 deletions(-)
>
> diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> index 27aacde60..6f526c203 100644
> --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
>  section in the Yocto Project Overview and Concepts Manual for additional
>  concepts on working in the Yocto Project development environment.
>
> -Two commonly used testing repositories exist for OpenEmbedded-Core:
> -
> --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> -   ``poky-contrib`` repository in the
> -   :yocto_git:`Yocto Project source repositories <>`.
> -
> --  *"master-next" branch:* This branch is part of the main "poky"
> -   repository in the Yocto Project source repositories.
> -
> -Maintainers use these branches to test submissions prior to merging
> -patches. Thus, you can get an idea of the status of a patch based on
> -whether the patch has been merged into one of these branches.
> +Maintainers commonly use ``-next`` branches to test submissions prior to
> +merging patches. Thus, you can get an idea of the status of a patch based on
> +whether the patch has been merged into one of these branches. The commonly
> +used testing branches for OpenEmbedded-Core are as follows:
> +
> +-  *openembedded-core "master-next" branch:* This branch is part of the
> +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> +   proposed changes to the core metadata.
> +
> +-  *poky "master-next" branch:* This branch is part of the
> +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> +   changes to bitbake, the core metadata and the poky distro.
> +
> +Similarly, stable branches maintained by the project may have corresponding
> +``-next`` branches which collect proposed changes. For example,
> +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> +"openembdedded-core" and "poky" repositories.

Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
here, so that the documentation stays 'current' over the years?
I think it's a good idea to keep 'dunfell-next' though (since it's
LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.

> +
> +Other layers may have similar testing branches but there is no formal
> +requirement or standard for these so please check the documentation for the
> +layers you are contributing to.
>
>  .. note::
>
> --
> 2.20.1
>
>
> 
>

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
<nicolas.dechesne@linaro.org> wrote:
>
> On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> >
> > After discussions on IRC with Ross we concluded that the `ross/mut`
> > branch shouldn't really be listed in the docs as it's more of a personal
> > test branch. Instead we should list the -next branches for
> > openembedded-core and poky.
> >
> > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > ---
> >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> >  1 file changed, 21 insertions(+), 12 deletions(-)
> >
> > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > index 27aacde60..6f526c203 100644
> > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> >  section in the Yocto Project Overview and Concepts Manual for additional
> >  concepts on working in the Yocto Project development environment.
> >
> > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > -
> > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > -   ``poky-contrib`` repository in the
> > -   :yocto_git:`Yocto Project source repositories <>`.
> > -
> > --  *"master-next" branch:* This branch is part of the main "poky"
> > -   repository in the Yocto Project source repositories.
> > -
> > -Maintainers use these branches to test submissions prior to merging
> > -patches. Thus, you can get an idea of the status of a patch based on
> > -whether the patch has been merged into one of these branches.
> > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > +merging patches. Thus, you can get an idea of the status of a patch based on
> > +whether the patch has been merged into one of these branches. The commonly
> > +used testing branches for OpenEmbedded-Core are as follows:
> > +
> > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains

I spotted a missed word here, it should be "and contains".

> > +   proposed changes to the core metadata.
> > +
> > +-  *poky "master-next" branch:* This branch is part of the
> > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > +   changes to bitbake, the core metadata and the poky distro.
> > +
> > +Similarly, stable branches maintained by the project may have corresponding
> > +``-next`` branches which collect proposed changes. For example,
> > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > +"openembdedded-core" and "poky" repositories.
>
> Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> here, so that the documentation stays 'current' over the years?
> I think it's a good idea to keep 'dunfell-next' though (since it's
> LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.

I agree it's worth changing these, I'll send a v3.

-- 
Paul Barker
Konsulko Group

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
<nicolas.dechesne@linaro.org> wrote:
>
> On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> >
> > After discussions on IRC with Ross we concluded that the `ross/mut`
> > branch shouldn't really be listed in the docs as it's more of a personal
> > test branch. Instead we should list the -next branches for
> > openembedded-core and poky.
> >
> > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > ---
> >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> >  1 file changed, 21 insertions(+), 12 deletions(-)
> >
> > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > index 27aacde60..6f526c203 100644
> > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> >  section in the Yocto Project Overview and Concepts Manual for additional
> >  concepts on working in the Yocto Project development environment.
> >
> > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > -
> > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > -   ``poky-contrib`` repository in the
> > -   :yocto_git:`Yocto Project source repositories <>`.
> > -
> > --  *"master-next" branch:* This branch is part of the main "poky"
> > -   repository in the Yocto Project source repositories.
> > -
> > -Maintainers use these branches to test submissions prior to merging
> > -patches. Thus, you can get an idea of the status of a patch based on
> > -whether the patch has been merged into one of these branches.
> > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > +merging patches. Thus, you can get an idea of the status of a patch based on
> > +whether the patch has been merged into one of these branches. The commonly
> > +used testing branches for OpenEmbedded-Core are as follows:
> > +
> > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> > +   proposed changes to the core metadata.
> > +
> > +-  *poky "master-next" branch:* This branch is part of the
> > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > +   changes to bitbake, the core metadata and the poky distro.
> > +
> > +Similarly, stable branches maintained by the project may have corresponding
> > +``-next`` branches which collect proposed changes. For example,
> > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > +"openembdedded-core" and "poky" repositories.
>
> Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> here, so that the documentation stays 'current' over the years?
> I think it's a good idea to keep 'dunfell-next' though (since it's
> LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.

I'm making the changes today and I realised this may lead to confusion
for the next LTS release. How about we define
DISTRO_NAME_NO_CAP_PREV_LTS and then we can say that it will never be
equal to DISTRO_NAME_NO_CAP?

-- 
Paul Barker
Konsulko Group

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Nicolas Dechesne]

On Mon, Nov 23, 2020 at 4:40 PM Paul Barker <pbarker@konsulko.com> wrote:
>
> On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
> <nicolas.dechesne@linaro.org> wrote:
> >
> > On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> > >
> > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > branch shouldn't really be listed in the docs as it's more of a personal
> > > test branch. Instead we should list the -next branches for
> > > openembedded-core and poky.
> > >
> > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > ---
> > >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> > >  1 file changed, 21 insertions(+), 12 deletions(-)
> > >
> > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > index 27aacde60..6f526c203 100644
> > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > >  section in the Yocto Project Overview and Concepts Manual for additional
> > >  concepts on working in the Yocto Project development environment.
> > >
> > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > -
> > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > -   ``poky-contrib`` repository in the
> > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > -
> > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > -   repository in the Yocto Project source repositories.
> > > -
> > > -Maintainers use these branches to test submissions prior to merging
> > > -patches. Thus, you can get an idea of the status of a patch based on
> > > -whether the patch has been merged into one of these branches.
> > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > +whether the patch has been merged into one of these branches. The commonly
> > > +used testing branches for OpenEmbedded-Core are as follows:
> > > +
> > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> > > +   proposed changes to the core metadata.
> > > +
> > > +-  *poky "master-next" branch:* This branch is part of the
> > > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > > +   changes to bitbake, the core metadata and the poky distro.
> > > +
> > > +Similarly, stable branches maintained by the project may have corresponding
> > > +``-next`` branches which collect proposed changes. For example,
> > > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > > +"openembdedded-core" and "poky" repositories.
> >
> > Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> > here, so that the documentation stays 'current' over the years?
> > I think it's a good idea to keep 'dunfell-next' though (since it's
> > LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> > points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.
>
> I'm making the changes today and I realised this may lead to confusion
> for the next LTS release. How about we define
> DISTRO_NAME_NO_CAP_PREV_LTS and then we can say that it will never be
> equal to DISTRO_NAME_NO_CAP?

I think we need:

DISTRO_NAME_NO_CAP : the current release
DISTRO_NAME_NO_CAP_MINUS_ONE : the previous release
DISTRO_NAME_NO_CAP_LTS : the current LTS release (and yes, it might be
DISTRO_NAME_NO_CAP right after an LTS)

Then we should be able to address pretty much anything we need, no?
Perhaps we can add DISTRO_NAME_NO_CAP_LTS_PREV eventually..


>
> --
> Paul Barker
> Konsulko Group

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Quentin Schulz]

Hi all,

On Mon, Nov 23, 2020 at 05:00:32PM +0100, Nicolas Dechesne wrote:
> On Mon, Nov 23, 2020 at 4:40 PM Paul Barker <pbarker@konsulko.com> wrote:
> >
> > On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
> > <nicolas.dechesne@linaro.org> wrote:
> > >
> > > On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> > > >
> > > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > > branch shouldn't really be listed in the docs as it's more of a personal
> > > > test branch. Instead we should list the -next branches for
> > > > openembedded-core and poky.
> > > >
> > > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > > ---
> > > >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> > > >  1 file changed, 21 insertions(+), 12 deletions(-)
> > > >
> > > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > index 27aacde60..6f526c203 100644
> > > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > > >  section in the Yocto Project Overview and Concepts Manual for additional
> > > >  concepts on working in the Yocto Project development environment.
> > > >
> > > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > > -
> > > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > > -   ``poky-contrib`` repository in the
> > > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > > -
> > > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > > -   repository in the Yocto Project source repositories.
> > > > -
> > > > -Maintainers use these branches to test submissions prior to merging
> > > > -patches. Thus, you can get an idea of the status of a patch based on
> > > > -whether the patch has been merged into one of these branches.
> > > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > > +whether the patch has been merged into one of these branches. The commonly
> > > > +used testing branches for OpenEmbedded-Core are as follows:
> > > > +
> > > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> > > > +   proposed changes to the core metadata.
> > > > +
> > > > +-  *poky "master-next" branch:* This branch is part of the
> > > > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > > > +   changes to bitbake, the core metadata and the poky distro.
> > > > +
> > > > +Similarly, stable branches maintained by the project may have corresponding
> > > > +``-next`` branches which collect proposed changes. For example,
> > > > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > > > +"openembdedded-core" and "poky" repositories.
> > >
> > > Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> > > here, so that the documentation stays 'current' over the years?
> > > I think it's a good idea to keep 'dunfell-next' though (since it's
> > > LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> > > points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.
> >
> > I'm making the changes today and I realised this may lead to confusion
> > for the next LTS release. How about we define
> > DISTRO_NAME_NO_CAP_PREV_LTS and then we can say that it will never be
> > equal to DISTRO_NAME_NO_CAP?
> 
> I think we need:
> 
> DISTRO_NAME_NO_CAP : the current release
> DISTRO_NAME_NO_CAP_MINUS_ONE : the previous release

Do we actually need this one?

> DISTRO_NAME_NO_CAP_LTS : the current LTS release (and yes, it might be
> DISTRO_NAME_NO_CAP right after an LTS)

Quentin

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

On Mon, 23 Nov 2020 at 16:00, Nicolas Dechesne
<nicolas.dechesne@linaro.org> wrote:
>
> On Mon, Nov 23, 2020 at 4:40 PM Paul Barker <pbarker@konsulko.com> wrote:
> >
> > On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
> > <nicolas.dechesne@linaro.org> wrote:
> > >
> > > On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> > > >
> > > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > > branch shouldn't really be listed in the docs as it's more of a personal
> > > > test branch. Instead we should list the -next branches for
> > > > openembedded-core and poky.
> > > >
> > > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > > ---
> > > >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> > > >  1 file changed, 21 insertions(+), 12 deletions(-)
> > > >
> > > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > index 27aacde60..6f526c203 100644
> > > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > > >  section in the Yocto Project Overview and Concepts Manual for additional
> > > >  concepts on working in the Yocto Project development environment.
> > > >
> > > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > > -
> > > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > > -   ``poky-contrib`` repository in the
> > > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > > -
> > > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > > -   repository in the Yocto Project source repositories.
> > > > -
> > > > -Maintainers use these branches to test submissions prior to merging
> > > > -patches. Thus, you can get an idea of the status of a patch based on
> > > > -whether the patch has been merged into one of these branches.
> > > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > > +whether the patch has been merged into one of these branches. The commonly
> > > > +used testing branches for OpenEmbedded-Core are as follows:
> > > > +
> > > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> > > > +   proposed changes to the core metadata.
> > > > +
> > > > +-  *poky "master-next" branch:* This branch is part of the
> > > > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > > > +   changes to bitbake, the core metadata and the poky distro.
> > > > +
> > > > +Similarly, stable branches maintained by the project may have corresponding
> > > > +``-next`` branches which collect proposed changes. For example,
> > > > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > > > +"openembdedded-core" and "poky" repositories.
> > >
> > > Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> > > here, so that the documentation stays 'current' over the years?
> > > I think it's a good idea to keep 'dunfell-next' though (since it's
> > > LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> > > points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.
> >
> > I'm making the changes today and I realised this may lead to confusion
> > for the next LTS release. How about we define
> > DISTRO_NAME_NO_CAP_PREV_LTS and then we can say that it will never be
> > equal to DISTRO_NAME_NO_CAP?
>
> I think we need:
>
> DISTRO_NAME_NO_CAP : the current release
> DISTRO_NAME_NO_CAP_MINUS_ONE : the previous release
> DISTRO_NAME_NO_CAP_LTS : the current LTS release (and yes, it might be
> DISTRO_NAME_NO_CAP right after an LTS)
>
> Then we should be able to address pretty much anything we need, no?

My only concern here is using DISTRO_NAME_NO_CAP and
DISTRO_NAME_NO_CAP_LTS in the same sentence as two examples, it'd be
confusing in the future when they may both be the same.

Maybe the solution is to just reference one other -next branch as an
example here instead of 2.

-- 
Paul Barker
Konsulko Group

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Nicolas Dechesne]

On Mon, Nov 23, 2020 at 5:08 PM Paul Barker <pbarker@konsulko.com> wrote:
>
> On Mon, 23 Nov 2020 at 16:00, Nicolas Dechesne
> <nicolas.dechesne@linaro.org> wrote:
> >
> > On Mon, Nov 23, 2020 at 4:40 PM Paul Barker <pbarker@konsulko.com> wrote:
> > >
> > > On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
> > > <nicolas.dechesne@linaro.org> wrote:
> > > >
> > > > On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> > > > >
> > > > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > > > branch shouldn't really be listed in the docs as it's more of a personal
> > > > > test branch. Instead we should list the -next branches for
> > > > > openembedded-core and poky.
> > > > >
> > > > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > > > ---
> > > > >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> > > > >  1 file changed, 21 insertions(+), 12 deletions(-)
> > > > >
> > > > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > > index 27aacde60..6f526c203 100644
> > > > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > > > >  section in the Yocto Project Overview and Concepts Manual for additional
> > > > >  concepts on working in the Yocto Project development environment.
> > > > >
> > > > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > > > -
> > > > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > > > -   ``poky-contrib`` repository in the
> > > > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > > > -
> > > > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > > > -   repository in the Yocto Project source repositories.
> > > > > -
> > > > > -Maintainers use these branches to test submissions prior to merging
> > > > > -patches. Thus, you can get an idea of the status of a patch based on
> > > > > -whether the patch has been merged into one of these branches.
> > > > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > > > +whether the patch has been merged into one of these branches. The commonly
> > > > > +used testing branches for OpenEmbedded-Core are as follows:
> > > > > +
> > > > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > > > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> > > > > +   proposed changes to the core metadata.
> > > > > +
> > > > > +-  *poky "master-next" branch:* This branch is part of the
> > > > > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > > > > +   changes to bitbake, the core metadata and the poky distro.
> > > > > +
> > > > > +Similarly, stable branches maintained by the project may have corresponding
> > > > > +``-next`` branches which collect proposed changes. For example,
> > > > > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > > > > +"openembdedded-core" and "poky" repositories.
> > > >
> > > > Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> > > > here, so that the documentation stays 'current' over the years?
> > > > I think it's a good idea to keep 'dunfell-next' though (since it's
> > > > LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> > > > points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.
> > >
> > > I'm making the changes today and I realised this may lead to confusion
> > > for the next LTS release. How about we define
> > > DISTRO_NAME_NO_CAP_PREV_LTS and then we can say that it will never be
> > > equal to DISTRO_NAME_NO_CAP?
> >
> > I think we need:
> >
> > DISTRO_NAME_NO_CAP : the current release
> > DISTRO_NAME_NO_CAP_MINUS_ONE : the previous release
> > DISTRO_NAME_NO_CAP_LTS : the current LTS release (and yes, it might be
> > DISTRO_NAME_NO_CAP right after an LTS)
> >
> > Then we should be able to address pretty much anything we need, no?
>
> My only concern here is using DISTRO_NAME_NO_CAP and
> DISTRO_NAME_NO_CAP_LTS in the same sentence as two examples, it'd be
> confusing in the future when they may both be the same.
>
> Maybe the solution is to just reference one other -next branch as an
> example here instead of 2.

I agree we should not use both in the same sentence. To me both have
different uses. In fact we never needed the LTS, because there was
never an LTS before.. but I suspect we will add more and more snippet
or sentences which will want to refer to the LTS, so adding it and
using it appropriately makes sense.

we can keep the 2 regluar one (release and prev release) for now, the
MINUS_ONE is used a very few places.. but i think it makes sense to
offer the possibility to refer to the previous release.


>
> --
> Paul Barker
> Konsulko Group

Re: [docs] [PATCH v2 2/9] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

On Mon, 23 Nov 2020 at 16:58, Nicolas Dechesne
<nicolas.dechesne@linaro.org> wrote:
>
> On Mon, Nov 23, 2020 at 5:08 PM Paul Barker <pbarker@konsulko.com> wrote:
> >
> > On Mon, 23 Nov 2020 at 16:00, Nicolas Dechesne
> > <nicolas.dechesne@linaro.org> wrote:
> > >
> > > On Mon, Nov 23, 2020 at 4:40 PM Paul Barker <pbarker@konsulko.com> wrote:
> > > >
> > > > On Wed, 18 Nov 2020 at 11:23, Nicolas Dechesne
> > > > <nicolas.dechesne@linaro.org> wrote:
> > > > >
> > > > > On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> > > > > >
> > > > > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > > > > branch shouldn't really be listed in the docs as it's more of a personal
> > > > > > test branch. Instead we should list the -next branches for
> > > > > > openembedded-core and poky.
> > > > > >
> > > > > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > > > > ---
> > > > > >  .../dev-manual/dev-manual-common-tasks.rst    | 33 ++++++++++++-------
> > > > > >  1 file changed, 21 insertions(+), 12 deletions(-)
> > > > > >
> > > > > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > > > index 27aacde60..6f526c203 100644
> > > > > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > > > @@ -10665,18 +10665,27 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > > > > >  section in the Yocto Project Overview and Concepts Manual for additional
> > > > > >  concepts on working in the Yocto Project development environment.
> > > > > >
> > > > > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > > > > -
> > > > > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > > > > -   ``poky-contrib`` repository in the
> > > > > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > > > > -
> > > > > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > > > > -   repository in the Yocto Project source repositories.
> > > > > > -
> > > > > > -Maintainers use these branches to test submissions prior to merging
> > > > > > -patches. Thus, you can get an idea of the status of a patch based on
> > > > > > -whether the patch has been merged into one of these branches.
> > > > > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > > > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > > > > +whether the patch has been merged into one of these branches. The commonly
> > > > > > +used testing branches for OpenEmbedded-Core are as follows:
> > > > > > +
> > > > > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > > > > +   :oe_git:`openembedded-core </openembedded-core/>` repository contains
> > > > > > +   proposed changes to the core metadata.
> > > > > > +
> > > > > > +-  *poky "master-next" branch:* This branch is part of the
> > > > > > +   :yocto_git:`poky </cgit/cgit.cgi/poky/>` repository and combines proposed
> > > > > > +   changes to bitbake, the core metadata and the poky distro.
> > > > > > +
> > > > > > +Similarly, stable branches maintained by the project may have corresponding
> > > > > > +``-next`` branches which collect proposed changes. For example,
> > > > > > +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> > > > > > +"openembdedded-core" and "poky" repositories.
> > > > >
> > > > > Perhaps using DISTRO_NAME_NO_CAP and DISTRO_NAME_NO_CAP_MINUS_ONE
> > > > > here, so that the documentation stays 'current' over the years?
> > > > > I think it's a good idea to keep 'dunfell-next' though (since it's
> > > > > LTS), so perhaps we can add DISTRO_NAME_NO_CAP_LTS variable which
> > > > > points to latest LTS, and use it and DISTRO_NAME_NO_CAP here.
> > > >
> > > > I'm making the changes today and I realised this may lead to confusion
> > > > for the next LTS release. How about we define
> > > > DISTRO_NAME_NO_CAP_PREV_LTS and then we can say that it will never be
> > > > equal to DISTRO_NAME_NO_CAP?
> > >
> > > I think we need:
> > >
> > > DISTRO_NAME_NO_CAP : the current release
> > > DISTRO_NAME_NO_CAP_MINUS_ONE : the previous release
> > > DISTRO_NAME_NO_CAP_LTS : the current LTS release (and yes, it might be
> > > DISTRO_NAME_NO_CAP right after an LTS)
> > >
> > > Then we should be able to address pretty much anything we need, no?
> >
> > My only concern here is using DISTRO_NAME_NO_CAP and
> > DISTRO_NAME_NO_CAP_LTS in the same sentence as two examples, it'd be
> > confusing in the future when they may both be the same.
> >
> > Maybe the solution is to just reference one other -next branch as an
> > example here instead of 2.
>
> I agree we should not use both in the same sentence. To me both have
> different uses. In fact we never needed the LTS, because there was
> never an LTS before.. but I suspect we will add more and more snippet
> or sentences which will want to refer to the LTS, so adding it and
> using it appropriately makes sense.
>
> we can keep the 2 regluar one (release and prev release) for now, the
> MINUS_ONE is used a very few places.. but i think it makes sense to
> offer the possibility to refer to the previous release.

Ok cool. I'll send v3 using DISTRO_NAME_NO_CAP and
DISTRO_NAME_NO_CAP_MINUS_ONE here. We can introduce
DISTRO_NAME_NO_CAP_LTS in a separate follow-up patch.

Thanks,

-- 
Paul Barker
Konsulko Group

[PATCH v2 3/9] dev-manual-common-tasks: Update & move patchwork reference

[Paul Barker]

Add a link to our patchwork instance and note how submitted patches are
checked for common mistakes. This note is moved to the section on
submitting patches via email as that is the place where most users will
run into patchwork/patchtest.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 23 +++++++++++--------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 6f526c203..d53f68cc1 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10687,16 +10687,6 @@ Other layers may have similar testing branches but there is no formal
 requirement or standard for these so please check the documentation for the
 layers you are contributing to.
 
-.. note::
-
-   This system is imperfect and changes can sometimes get lost in the
-   flow. Asking about the status of a patch or change is reasonable if
-   the change has been idle for a while with no feedback. The Yocto
-   Project does have plans to use
-   `Patchwork <https://en.wikipedia.org/wiki/Patchwork_(software)>`__
-   to track the status of patches and also to automatically preview
-   patches.
-
 The following sections provide procedures for submitting a change.
 
 .. _pushing-a-change-upstream:
@@ -10991,6 +10981,19 @@ without using the scripts:
    command, see ``GIT-SEND-EMAIL(1)`` displayed using the
    ``man git-send-email`` command.
 
+The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
+to track the status of patches submitted to the various mailing lists and to
+support automated patch testing. Each submitted patch is checked for common
+mistakes and deviations from the expected patch format and submitters are
+notified by patchtest if such mistakes are found. This process helps to
+reduce the burden of patch review on maintainers.
+
+.. note::
+
+   This system is imperfect and changes can sometimes get lost in the flow.
+   Asking about the status of a patch or change is reasonable if the change
+   has been idle for a while with no feedback.
+
 Working With Licenses
 =====================
 
-- 
2.20.1

[PATCH v2 4/9] dev-manual-common-tasks: Tidy up patch submission process

[Paul Barker]

Reduce duplication by pulling out the common steps of committing changes
locally from the steps of submitting those changes via the pull request
scripts or via email.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 63 ++++++++-----------
 1 file changed, 25 insertions(+), 38 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index d53f68cc1..72481ae50 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10689,19 +10689,10 @@ layers you are contributing to.
 
 The following sections provide procedures for submitting a change.
 
-.. _pushing-a-change-upstream:
-
-Using Scripts to Push a Change Upstream and Request a Pull
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Follow this procedure to push a change to an upstream "contrib" Git
-repository:
+.. _preparing-changes-for-submissions:
 
-.. note::
-
-   You can find general Git information on how to push a change upstream
-   in the
-   `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__.
+Preparing Changes for Submission
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 1. *Make Your Changes Locally:* Make your changes in your local Git
    repository. You should make small, controlled, isolated changes.
@@ -10783,7 +10774,22 @@ repository:
 
          detailed description of change
 
-4. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for
+.. _pushing-a-change-upstream:
+
+Using Scripts to Push a Change Upstream and Request a Pull
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow this procedure to push a change to an upstream "contrib" Git
+repository once the steps in :ref:`preparing-changes-for-submissions` have
+been followed:
+
+.. note::
+
+   You can find general Git information on how to push a change upstream
+   in the
+   `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__.
+
+1. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for
    permissions to push to an upstream contrib repository, push the
    change to that repository:
    ::
@@ -10800,7 +10806,7 @@ repository:
 
       $ git push meta-intel-contrib your_name/README
 
-5. *Determine Who to Notify:* Determine the maintainer or the mailing
+2. *Determine Who to Notify:* Determine the maintainer or the mailing
    list that you need to notify for the change.
 
    Before submitting any change, you need to be sure who the maintainer
@@ -10829,7 +10835,7 @@ repository:
       lists <resources-mailinglist>`" section in
       the Yocto Project Reference Manual.
 
-6. *Make a Pull Request:* Notify the maintainer or the mailing list that
+3. *Make a Pull Request:* Notify the maintainer or the mailing list that
    you have pushed a change by making a pull request.
 
    The Yocto Project provides two scripts that conveniently let you
@@ -10896,29 +10902,10 @@ mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in
 Yocto Project Reference Manual.
 
 Here is the general procedure on how to submit a patch through email
-without using the scripts:
-
-1. *Make Your Changes Locally:* Make your changes in your local Git
-   repository. You should make small, controlled, isolated changes.
-   Keeping changes small and isolated aids review, makes
-   merging/rebasing easier and keeps the change history clean should
-   anyone need to refer to it in future.
-
-2. *Stage Your Changes:* Stage your changes by using the ``git add``
-   command on each file you changed.
-
-3. *Commit Your Changes:* Commit the change by using the
-   ``git commit --signoff`` command. Using the ``--signoff`` option
-   identifies you as the person making the change and also satisfies the
-   Developer's Certificate of Origin (DCO) shown earlier.
-
-   When you form a commit, you must follow certain standards established
-   by the Yocto Project development team. See :ref:`Step 3
-   <dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull>`
-   in the previous section for information on how to provide commit information
-   that meets Yocto Project commit message standards.
+without using the scripts once the steps in
+:ref:`preparing-changes-for-submissions` have been followed:
 
-4. *Format the Commit:* Format the commit into an email message. To
+1. *Format the Commit:* Format the commit into an email message. To
    format commits, use the ``git format-patch`` command. When you
    provide the command, you must include a revision list or a number of
    patches as part of the command. For example, either of these two
@@ -10951,7 +10938,7 @@ without using the scripts:
       or to OpenEmbedded, you might consider requesting a contrib area
       and the necessary associated rights.
 
-5. *Import the Files Into Your Mail Client:* Import the files into your
+2. *Import the Files Into Your Mail Client:* Import the files into your
    mail client by using the ``git send-email`` command.
 
    .. note::
-- 
2.20.1

[PATCH v2 5/9] dev-manual-common-tasks: Describe git-send-email accurately

[Paul Barker]

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 documentation/dev-manual/dev-manual-common-tasks.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 72481ae50..42163cb9b 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10938,8 +10938,8 @@ without using the scripts once the steps in
       or to OpenEmbedded, you might consider requesting a contrib area
       and the necessary associated rights.
 
-2. *Import the Files Into Your Mail Client:* Import the files into your
-   mail client by using the ``git send-email`` command.
+2. *Send the patches via email:* Send the patches to the recipients and
+   relevant mailing lists by using the ``git send-email`` command.
 
    .. note::
 
-- 
2.20.1

[PATCH v2 6/9] dev-manual-common-tasks: Describe how to handle patch feedback

[Paul Barker]

The contribution guidelines would benefit from a brief section on how to
address feedback from patch reviewers and how to re-submit amended
patches. The information here is based on my personal experience and on
the existing notes on the "How to submit a patch to OpenEmbedded" page
on the OE wiki.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 42163cb9b..61e66f464 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10981,6 +10981,28 @@ reduce the burden of patch review on maintainers.
    Asking about the status of a patch or change is reasonable if the change
    has been idle for a while with no feedback.
 
+Responding to Patch Review
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may get feedback on your submitted patches from other community members
+or from the automated patchtest service. If issues are identified in your
+patch then it is usually necessary to address these before the patch will be
+accepted into the project. In this case you should amend the patch according
+to the feedback and submit an updated version to the relevant mailing list,
+copying in the reviewers who provided feedback to the previous version of the
+patch.
+
+The patch should be amended using ``git commit --amend`` or perhaps ``git
+rebase`` for more expert git users. You should also modify the ``[PATCH]``
+tag in the email subject line when sending the revised patch to mark the new
+iteration as ``[PATCH v2]``, ``[PATCH v3]``, etc as appropriate. This can be
+done by passing the ``-v`` argument to ``git format-patch`` with a version
+number.
+
+Lastly please ensure that you also test your revised changes. In particular
+please don't just edit the patch file written out by ``git format-patch`` and
+resend it.
+
 Working With Licenses
 =====================
 
-- 
2.20.1

[PATCH v2 7/9] dev-manual-common-tasks: Describe how to propose changes to stable branches

[Paul Barker]

The documentation on submitting changes to the project should cover the
ways in which the process differs for stable branches. These changes add
a brief description of the typical policy for handling changes to stable
branches and give some steps to follow when proposing changes to these
branches. The information is based on my personal experience and on the
existing content of the "How to submit a patch to OpenEmbedded" page on
the OE wiki.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 61e66f464..700c60ab2 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -11003,6 +11003,63 @@ Lastly please ensure that you also test your revised changes. In particular
 please don't just edit the patch file written out by ``git format-patch`` and
 resend it.
 
+Submitting Changes to Stable Release Branches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The process for proposing changes to a Yocto Project stable branch differs
+from the steps described above. Changes to a stable branch must address
+identified bugs or CVEs and should be made carefully in order to avoid the
+risk of introducing new bugs or breaking backwards compatibility. Typically
+bug fixes must already be accepted into the master branch before they can be
+backported to a stable branch unless the bug in question does not affect the
+master branch or the fix on the master branch is unsuitable for backporting.
+
+The list of stable branches along with the status and maintainer for each
+branch can be obtained from the
+:yocto_wiki:`Releases wiki page </wiki/Releases>`.
+
+.. note::
+
+   Changes will not typically be accepted for branches which are marked as
+   End-Of-Life (EOL).
+
+With this in mind, the steps to submit a change for a stable branch are as
+follows:
+
+1. *Identify the bug or CVE to be fixed:* This information should be
+   collected so that it can be included in your submission.
+
+2. *Check if the fix is already present in the master branch:* This will
+   result in the most straightforward path into the stable branch for the
+   fix.
+
+   a. *If the fix is present in the master branch - Submit a backport request
+      by email:* You should send an email to the relevant stable branch
+      maintainer and the mailing list with details of the bug or CVE to be
+      fixed, the commit hash on the master branch that fixes the issue and
+      the stable branches which you would like this fix to be backported to.
+
+   b. *If the fix is not present in the master branch - Submit the fix to the
+      master branch first:* This will ensure that the fix passes through the
+      project's usual patch review and test processes before being accepted.
+      It will also ensure that bugs are not left unresolved in the master
+      branch itself. Once the fix is accepted in the master branch a backport
+      request can be submitted as above.
+
+   c. *If the fix is unsuitable for the master branch - Submit a patch
+      directly for the stable branch:* This method should be considered as a
+      last resort. It is typically necessary when the master branch is using
+      a newer version of the software which includes an upstream fix for the
+      issue or when the issue has been fixed on the master branch in a way
+      that introduces backwards incompatible changes. In this case follow the
+      steps in :ref:`preparing-changes-for-submissions` and
+      :ref:`submitting-a-patch` but modify the subject header of your patch
+      email to include the name of the stable branch which you are
+      targetting. This can be done using the ``--subject-prefix`` argument to
+      ``git format-patch``, for example to submit a patch to the dunfell
+      branch use
+      ``git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ...``.
+
 Working With Licenses
 =====================
 
-- 
2.20.1

Re: [docs] [PATCH v2 7/9] dev-manual-common-tasks: Describe how to propose changes to stable branches

[Nicolas Dechesne]

On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
>
> The documentation on submitting changes to the project should cover the
> ways in which the process differs for stable branches. These changes add
> a brief description of the typical policy for handling changes to stable
> branches and give some steps to follow when proposing changes to these
> branches. The information is based on my personal experience and on the
> existing content of the "How to submit a patch to OpenEmbedded" page on
> the OE wiki.
>
> Signed-off-by: Paul Barker <pbarker@konsulko.com>
> ---
>  .../dev-manual/dev-manual-common-tasks.rst    | 57 +++++++++++++++++++
>  1 file changed, 57 insertions(+)
>
> diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> index 61e66f464..700c60ab2 100644
> --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> @@ -11003,6 +11003,63 @@ Lastly please ensure that you also test your revised changes. In particular
>  please don't just edit the patch file written out by ``git format-patch`` and
>  resend it.
>
> +Submitting Changes to Stable Release Branches
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The process for proposing changes to a Yocto Project stable branch differs
> +from the steps described above. Changes to a stable branch must address
> +identified bugs or CVEs and should be made carefully in order to avoid the
> +risk of introducing new bugs or breaking backwards compatibility. Typically
> +bug fixes must already be accepted into the master branch before they can be
> +backported to a stable branch unless the bug in question does not affect the
> +master branch or the fix on the master branch is unsuitable for backporting.
> +
> +The list of stable branches along with the status and maintainer for each
> +branch can be obtained from the
> +:yocto_wiki:`Releases wiki page </wiki/Releases>`.
> +
> +.. note::
> +
> +   Changes will not typically be accepted for branches which are marked as
> +   End-Of-Life (EOL).
> +
> +With this in mind, the steps to submit a change for a stable branch are as
> +follows:
> +
> +1. *Identify the bug or CVE to be fixed:* This information should be
> +   collected so that it can be included in your submission.
> +
> +2. *Check if the fix is already present in the master branch:* This will
> +   result in the most straightforward path into the stable branch for the
> +   fix.
> +
> +   a. *If the fix is present in the master branch - Submit a backport request
> +      by email:* You should send an email to the relevant stable branch
> +      maintainer and the mailing list with details of the bug or CVE to be
> +      fixed, the commit hash on the master branch that fixes the issue and
> +      the stable branches which you would like this fix to be backported to.
> +
> +   b. *If the fix is not present in the master branch - Submit the fix to the
> +      master branch first:* This will ensure that the fix passes through the
> +      project's usual patch review and test processes before being accepted.
> +      It will also ensure that bugs are not left unresolved in the master
> +      branch itself. Once the fix is accepted in the master branch a backport
> +      request can be submitted as above.
> +
> +   c. *If the fix is unsuitable for the master branch - Submit a patch
> +      directly for the stable branch:* This method should be considered as a
> +      last resort. It is typically necessary when the master branch is using
> +      a newer version of the software which includes an upstream fix for the
> +      issue or when the issue has been fixed on the master branch in a way
> +      that introduces backwards incompatible changes. In this case follow the
> +      steps in :ref:`preparing-changes-for-submissions` and
> +      :ref:`submitting-a-patch` but modify the subject header of your patch
> +      email to include the name of the stable branch which you are
> +      targetting. This can be done using the ``--subject-prefix`` argument to
> +      ``git format-patch``, for example to submit a patch to the dunfell
> +      branch use
> +      ``git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ...``.

looks like we really need DISTRO_NAME_NO_CAP_LTS!

> +
>  Working With Licenses
>  =====================
>
> --
> 2.20.1
>
>
> 
>

[PATCH v2 8/9] dev-manual-common-tasks: Re-order patch submission instructions

[Paul Barker]

New contributors to the project will usually be following the steps to
submit patches directly via email as they may not have commit access to
a contrib repository. For shorter series of patches this is the more
common workflow which we see anyway.

The documentation here is updated to reflect this, addressing the email
submission process first and then the pull request process. The new
opening paragraph for the section on submitting pull requests is taken
from the "How to submit a patch to OpenEmbedded" page on the OE wiki.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 196 +++++++++---------
 1 file changed, 99 insertions(+), 97 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 700c60ab2..d92d01956 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10774,11 +10774,110 @@ Preparing Changes for Submission
 
          detailed description of change
 
+.. _submitting-a-patch:
+
+Using Email to Submit a Patch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Depending on the components changed, you need to submit the email to a
+specific mailing list. For some guidance on which mailing list to use,
+see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
+beginning of this section. For a description of all the available
+mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
+Yocto Project Reference Manual.
+
+Here is the general procedure on how to submit a patch through email
+without using the scripts once the steps in
+:ref:`preparing-changes-for-submissions` have been followed:
+
+1. *Format the Commit:* Format the commit into an email message. To
+   format commits, use the ``git format-patch`` command. When you
+   provide the command, you must include a revision list or a number of
+   patches as part of the command. For example, either of these two
+   commands takes your most recent single commit and formats it as an
+   email message in the current directory:
+   ::
+
+      $ git format-patch -1
+
+   or ::
+
+      $ git format-patch HEAD~
+
+   After the command is run, the current directory contains a numbered
+   ``.patch`` file for the commit.
+
+   If you provide several commits as part of the command, the
+   ``git format-patch`` command produces a series of numbered files in
+   the current directory – one for each commit. If you have more than
+   one patch, you should also use the ``--cover`` option with the
+   command, which generates a cover letter as the first "patch" in the
+   series. You can then edit the cover letter to provide a description
+   for the series of patches. For information on the
+   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
+   using the ``man git-format-patch`` command.
+
+   .. note::
+
+      If you are or will be a frequent contributor to the Yocto Project
+      or to OpenEmbedded, you might consider requesting a contrib area
+      and the necessary associated rights.
+
+2. *Send the patches via email:* Send the patches to the recipients and
+   relevant mailing lists by using the ``git send-email`` command.
+
+   .. note::
+
+      In order to use ``git send-email``, you must have the proper Git packages
+      installed on your host.
+      For Ubuntu, Debian, and Fedora the package is ``git-email``.
+
+   The ``git send-email`` command sends email by using a local or remote
+   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
+   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
+   file. If you are submitting patches through email only, it is very
+   important that you submit them without any whitespace or HTML
+   formatting that either you or your mailer introduces. The maintainer
+   that receives your patches needs to be able to save and apply them
+   directly from your emails. A good way to verify that what you are
+   sending will be applicable by the maintainer is to do a dry run and
+   send them to yourself and then save and apply them as the maintainer
+   would.
+
+   The ``git send-email`` command is the preferred method for sending
+   your patches using email since there is no risk of compromising
+   whitespace in the body of the message, which can occur when you use
+   your own mail client. The command also has several options that let
+   you specify recipients and perform further editing of the email
+   message. For information on how to use the ``git send-email``
+   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
+   ``man git-send-email`` command.
+
+The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
+to track the status of patches submitted to the various mailing lists and to
+support automated patch testing. Each submitted patch is checked for common
+mistakes and deviations from the expected patch format and submitters are
+notified by patchtest if such mistakes are found. This process helps to
+reduce the burden of patch review on maintainers.
+
+.. note::
+
+   This system is imperfect and changes can sometimes get lost in the flow.
+   Asking about the status of a patch or change is reasonable if the change
+   has been idle for a while with no feedback.
+
 .. _pushing-a-change-upstream:
 
 Using Scripts to Push a Change Upstream and Request a Pull
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+For larger patch series it is preferable to send a pull request which not
+only includes the patch but also a pointer to a branch that can be pulled
+from. This involves making a local branch for your changes, pushing this
+branch to an accessible repository and then using the ``create-pull-request``
+and ``send-pull-request`` scripts from openembedded-core to create and send a
+patch series with a link to the branch for review.
+
 Follow this procedure to push a change to an upstream "contrib" Git
 repository once the steps in :ref:`preparing-changes-for-submissions` have
 been followed:
@@ -10884,103 +10983,6 @@ been followed:
               $ poky/scripts/create-pull-request -h
               $ poky/scripts/send-pull-request -h
 
-
-.. _submitting-a-patch:
-
-Using Email to Submit a Patch
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can submit patches without using the ``create-pull-request`` and
-``send-pull-request`` scripts described in the previous section.
-However, keep in mind, the preferred method is to use the scripts.
-
-Depending on the components changed, you need to submit the email to a
-specific mailing list. For some guidance on which mailing list to use,
-see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
-beginning of this section. For a description of all the available
-mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
-Yocto Project Reference Manual.
-
-Here is the general procedure on how to submit a patch through email
-without using the scripts once the steps in
-:ref:`preparing-changes-for-submissions` have been followed:
-
-1. *Format the Commit:* Format the commit into an email message. To
-   format commits, use the ``git format-patch`` command. When you
-   provide the command, you must include a revision list or a number of
-   patches as part of the command. For example, either of these two
-   commands takes your most recent single commit and formats it as an
-   email message in the current directory:
-   ::
-
-      $ git format-patch -1
-
-   or ::
-
-      $ git format-patch HEAD~
-
-   After the command is run, the current directory contains a numbered
-   ``.patch`` file for the commit.
-
-   If you provide several commits as part of the command, the
-   ``git format-patch`` command produces a series of numbered files in
-   the current directory – one for each commit. If you have more than
-   one patch, you should also use the ``--cover`` option with the
-   command, which generates a cover letter as the first "patch" in the
-   series. You can then edit the cover letter to provide a description
-   for the series of patches. For information on the
-   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
-   using the ``man git-format-patch`` command.
-
-   .. note::
-
-      If you are or will be a frequent contributor to the Yocto Project
-      or to OpenEmbedded, you might consider requesting a contrib area
-      and the necessary associated rights.
-
-2. *Send the patches via email:* Send the patches to the recipients and
-   relevant mailing lists by using the ``git send-email`` command.
-
-   .. note::
-
-      In order to use ``git send-email``, you must have the proper Git packages
-      installed on your host.
-      For Ubuntu, Debian, and Fedora the package is ``git-email``.
-
-   The ``git send-email`` command sends email by using a local or remote
-   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
-   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
-   file. If you are submitting patches through email only, it is very
-   important that you submit them without any whitespace or HTML
-   formatting that either you or your mailer introduces. The maintainer
-   that receives your patches needs to be able to save and apply them
-   directly from your emails. A good way to verify that what you are
-   sending will be applicable by the maintainer is to do a dry run and
-   send them to yourself and then save and apply them as the maintainer
-   would.
-
-   The ``git send-email`` command is the preferred method for sending
-   your patches using email since there is no risk of compromising
-   whitespace in the body of the message, which can occur when you use
-   your own mail client. The command also has several options that let
-   you specify recipients and perform further editing of the email
-   message. For information on how to use the ``git send-email``
-   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
-   ``man git-send-email`` command.
-
-The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
-to track the status of patches submitted to the various mailing lists and to
-support automated patch testing. Each submitted patch is checked for common
-mistakes and deviations from the expected patch format and submitters are
-notified by patchtest if such mistakes are found. This process helps to
-reduce the burden of patch review on maintainers.
-
-.. note::
-
-   This system is imperfect and changes can sometimes get lost in the flow.
-   Asking about the status of a patch or change is reasonable if the change
-   has been idle for a while with no feedback.
-
 Responding to Patch Review
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.20.1

[PATCH v2 9/9] documentation/README: Refer to top-level README for contributions

[Paul Barker]

This may help anyone looking for patch contribution guidelines in the
documentation directory itself.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 documentation/README | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/README b/documentation/README
index 28d5c4be8..b0a3cb1dc 100644
--- a/documentation/README
+++ b/documentation/README
@@ -325,3 +325,9 @@ References to the bitbake manual can be done like this:
   See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
 or
   :term:`bitbake:BB_NUMBER_PARSE_THREADS`
+
+Submitting documentation changes
+================================
+
+Please see the top level README file in this repository for details of where
+to send patches.
-- 
2.20.1

Re: [docs] [PATCH v2 1/9] conf.py: Add oe_git directive

[Nicolas Dechesne]

On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
>
> This simplifies linking to git repositories on openembedded.org.
>
> Signed-off-by: Paul Barker <pbarker@konsulko.com>

Thanks Paul!. I reviewed the whole series. made a suggestion about a
new variable for the LTS name. It can be done in a v3, or a later
series as well, i don't mind much.
For the whole series:
Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>

> ---
>  documentation/conf.py | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/documentation/conf.py b/documentation/conf.py
> index a8df6e8f8..96118abec 100644
> --- a/documentation/conf.py
> +++ b/documentation/conf.py
> @@ -78,6 +78,7 @@ extlinks = {
>      'yocto_git': ('https://git.yoctoproject.org%s', None),
>      'oe_home': ('https://www.openembedded.org%s', None),
>      'oe_lists': ('https://lists.openembedded.org%s', None),
> +    'oe_git': ('https://git.openembedded.org%s', None),
>  }
>
>  # Intersphinx config to use cross reference with Bitbake user manual
> --
> 2.20.1
>
>
> 
>

Re: [docs] [PATCH v2 1/9] conf.py: Add oe_git directive

[Quentin Schulz]

Hi all,

On Wed, Nov 18, 2020 at 12:42:21PM +0100, Nicolas Dechesne wrote:
> On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> >
> > This simplifies linking to git repositories on openembedded.org.
> >
> > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> 
> Thanks Paul!. I reviewed the whole series. made a suggestion about a
> new variable for the LTS name. It can be done in a v3, or a later
> series as well, i don't mind much.

+1 for LTS variables in poky.yaml, though maybe we can just replace
_MINUS_ONE variables with LTS ones? From the quick look I had in the
docs, it seems to not be that big of a deal to migrate MINUS_ONE
variables to LTS ones and still keep more or less the same intended
behavior/explanation.

Also, throwing this out right now, I really don't like:
:yocto_git:`poky </cgit.cgi/poky>` lines.. Couldn't we just set
:yocto_git: to https://git.yoctoproject.org/cgit.cgi%s instead? and then
use it like that: :yocto_git:`/poky`?

Nothing to be changed in this patch series though, just thinking out
loud.

For the whole series:
Reviewed-by: Quentin Schulz <quentin.schulz@streamunlimited.com>

Thanks!
Quentin

Re: [docs] [PATCH v2 1/9] conf.py: Add oe_git directive

[Nicolas Dechesne]

On Wed, Nov 18, 2020 at 3:39 PM Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> Hi all,
>
> On Wed, Nov 18, 2020 at 12:42:21PM +0100, Nicolas Dechesne wrote:
> > On Wed, Nov 18, 2020 at 11:07 AM Paul Barker <pbarker@konsulko.com> wrote:
> > >
> > > This simplifies linking to git repositories on openembedded.org.
> > >
> > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> >
> > Thanks Paul!. I reviewed the whole series. made a suggestion about a
> > new variable for the LTS name. It can be done in a v3, or a later
> > series as well, i don't mind much.
>
> +1 for LTS variables in poky.yaml, though maybe we can just replace
> _MINUS_ONE variables with LTS ones? From the quick look I had in the
> docs, it seems to not be that big of a deal to migrate MINUS_ONE
> variables to LTS ones and still keep more or less the same intended
> behavior/explanation.
>
> Also, throwing this out right now, I really don't like:
> :yocto_git:`poky </cgit.cgi/poky>` lines.. Couldn't we just set
> :yocto_git: to https://git.yoctoproject.org/cgit.cgi%s instead? and then
> use it like that: :yocto_git:`/poky`?

Yes, I agreed. I even noted it down on my todo list. I remember
wanting that change when reviewing one of your earlier patch!

>
> Nothing to be changed in this patch series though, just thinking out
> loud.
>
> For the whole series:
> Reviewed-by: Quentin Schulz <quentin.schulz@streamunlimited.com>
>
> Thanks!
> Quentin