| Message ID | 20260922183249.2433345-6-twoerner@gmail.com |
|---|---|
| State | Under Review |
| Headers | show |
| Series | docs: editorial repairs to the examples | expand |
Hi Trevor, On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote: > Values the reader is expected to replace are written as though they were > literal. "arch-gdb" reads like a command that exists, a Git SRC_URI > example reads like a URL and a pair of revisions worth copying, and the > git-config examples give an account name and address that are somebody > else's. Put them in the angle brackets the manuals already use for the > purpose. > > Two corrections go with them: the directory placeholder in the GDB > example described itself at length rather than naming the thing, and the > smtppass example carried a stray "=". Since git config takes a name and > then a value, that "=" was the value, and the password behind it an > argument git config reads as a pattern. > > AI-Generated: codex/claude-opus 5 (xhigh) > Signed-off-by: Trevor Woerner <twoerner@gmail.com> > --- > changes in v2: > - rebased on master-next; no other change > --- > .../contributor-guide/submit-changes.rst | 12 ++++++------ > documentation/dev-manual/debugging.rst | 8 ++++---- > documentation/migration-guides/migration-5.2.rst | 16 ++++++++-------- > documentation/ref-manual/devtool-reference.rst | 2 +- > documentation/ref-manual/variables.rst | 2 +- > 5 files changed, 20 insertions(+), 20 deletions(-) > > diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst > index e60f8ca7ace3..a283eb734768 100644 > --- a/documentation/contributor-guide/submit-changes.rst > +++ b/documentation/contributor-guide/submit-changes.rst > @@ -62,8 +62,8 @@ on Debian and Ubuntu:: > Then, you need to set a name and e-mail address that Git will > use to identify your commits:: > > - $ git config --global user.name "Ada Lovelace" > - $ git config --global user.email "ada.lovelace@gmail.com" > + $ git config --global user.name "<name>" <firstname> <lastname> maybe? I'm guessing some cultures have other orders, I've seen <lastname>, <firstname> a few times. > + $ git config --global user.email "<email>" > > By default, Git adds a signature line at the end of patches containing the Git > version. We suggest to remove it as it doesn't add useful information. > @@ -399,8 +399,8 @@ regular STMP server, using a Google Mail account as an example:: > $ git config --global sendemail.smtpserver smtp.gmail.com Why is this not changed to a placeholder? > $ git config --global sendemail.smtpserverport 587 > $ git config --global sendemail.smtpencryption tls > - $ git config --global sendemail.smtpuser ada.lovelace@gmail.com > - $ git config --global sendemail.smtppass = XXXXXXXX > + $ git config --global sendemail.smtpuser <email> > + $ git config --global sendemail.smtppass <password> It's also optional, in which case you're prompted every time you send a mail, which I kinda like :) > > These settings will appear in the ``.gitconfig`` file in your home directory. > > @@ -509,7 +509,7 @@ We have a frequent issue with contributors whose patches are received through > a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is > a typical example for people sending from a domain name with :wikipedia:`DMARC`:: > > - From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>" > + From: "xxx via lists.openembedded.org <xxx@lists.openembedded.org>" Please keep this one (or use an example that exists in the wild, I don't think Linus sent patches to OE-Core :)) as it is an actual example. > > This ``From`` field is used by ``git am`` to recreate commits with the right > author name. The following will ensure that your e-mails have an additional > @@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional > maintainers accepting your patches don't have to fix commit author information > manually:: > > - $ git config --global sendemail.from "linus.torvalds@kernel.org" > + $ git config --global sendemail.from "<email>" > > The ``sendemail.from`` should match your ``user.email`` setting, > which appears in the ``Signed-off-by`` line of your commits. > diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst > index 0f6e9d1d7e85..8412c997a51e 100644 > --- a/documentation/dev-manual/debugging.rst > +++ b/documentation/dev-manual/debugging.rst > @@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard`` > Makefile target. Here is some abbreviated, sample output with the > missing dependency clearly visible at the end:: > > - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... > + i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot> > . > . > . > @@ -1114,11 +1114,11 @@ debugger. > After running gdbserver on the target, you need to run Gdb on the > host and configure it and connect to the target. Use these commands:: > > - $ cd directory-holding-the-debugfs-directory > - $ arch-gdb > + $ cd <debugfs-directory> > + $ <arch>-gdb > (gdb) set sysroot debugfs > (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug > - (gdb) target remote IP-of-target:1234 > + (gdb) target remote <IP-of-target>:1234 Here's yet another prompt we should support that I don't think it's supported in patch 2/8. > > At this > point, everything should automatically load (i.e. matching binaries, > diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst > index 77a11fe27047..48f9e7485d93 100644 > --- a/documentation/migration-guides/migration-5.2.rst > +++ b/documentation/migration-guides/migration-5.2.rst > @@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was > removed from BitBake, which means the following syntax is not supported > anymore:: > > - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY" > - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" > - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy" > + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>" > + SRCREV_<nameX> = "<revisionX>" > + SRCREV_<nameY> = "<revisionY>" We should say that this is the full sha of the commit. > > This was rarely used in the core repositories because it would only ever make > sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes > @@ -205,10 +205,10 @@ places. > If one of your recipes is using this mechanism, you can split the code source > fetching into two separate entries:: > > - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \ > - git://some.host/somepath;bareclone=1;branch=branchY;name=nameY" > - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" > - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy" > + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \ > + git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>" > + SRCREV_<nameX> = "<revisionX>" > + SRCREV_<nameY> = "<revisionY>" > Ditto. Cheers, Quentin
On Wed 2026-09-23 @ 12:57:39 PM, Quentin Schulz wrote: > Hi Trevor, > > On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote: > > Values the reader is expected to replace are written as though they were > > literal. "arch-gdb" reads like a command that exists, a Git SRC_URI > > example reads like a URL and a pair of revisions worth copying, and the > > git-config examples give an account name and address that are somebody > > else's. Put them in the angle brackets the manuals already use for the > > purpose. > > > > Two corrections go with them: the directory placeholder in the GDB > > example described itself at length rather than naming the thing, and the > > smtppass example carried a stray "=". Since git config takes a name and > > then a value, that "=" was the value, and the password behind it an > > argument git config reads as a pattern. > > > > AI-Generated: codex/claude-opus 5 (xhigh) > > Signed-off-by: Trevor Woerner <twoerner@gmail.com> > > --- > > changes in v2: > > - rebased on master-next; no other change > > --- > > .../contributor-guide/submit-changes.rst | 12 ++++++------ > > documentation/dev-manual/debugging.rst | 8 ++++---- > > documentation/migration-guides/migration-5.2.rst | 16 ++++++++-------- > > documentation/ref-manual/devtool-reference.rst | 2 +- > > documentation/ref-manual/variables.rst | 2 +- > > 5 files changed, 20 insertions(+), 20 deletions(-) > > > > diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst > > index e60f8ca7ace3..a283eb734768 100644 > > --- a/documentation/contributor-guide/submit-changes.rst > > +++ b/documentation/contributor-guide/submit-changes.rst > > @@ -62,8 +62,8 @@ on Debian and Ubuntu:: > > Then, you need to set a name and e-mail address that Git will > > use to identify your commits:: > > - $ git config --global user.name "Ada Lovelace" > > - $ git config --global user.email "ada.lovelace@gmail.com" > > + $ git config --global user.name "<name>" > > <firstname> <lastname> Sounds good, i like the above one. > maybe? I'm guessing some cultures have other orders, I've seen > > <lastname>, <firstname> > > a few times. > > > + $ git config --global user.email "<email>" > > By default, Git adds a signature line at the end of patches containing the Git > > version. We suggest to remove it as it doesn't add useful information. > > @@ -399,8 +399,8 @@ regular STMP server, using a Google Mail account as an example:: > > $ git config --global sendemail.smtpserver smtp.gmail.com > > Why is this not changed to a placeholder? Sounds good. > > $ git config --global sendemail.smtpserverport 587 > > $ git config --global sendemail.smtpencryption tls > > - $ git config --global sendemail.smtpuser ada.lovelace@gmail.com > > - $ git config --global sendemail.smtppass = XXXXXXXX > > + $ git config --global sendemail.smtpuser <email> > > + $ git config --global sendemail.smtppass <password> > > It's also optional, in which case you're prompted every time you send a > mail, which I kinda like :) > > > These settings will appear in the ``.gitconfig`` file in your home directory. > > @@ -509,7 +509,7 @@ We have a frequent issue with contributors whose patches are received through > > a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is > > a typical example for people sending from a domain name with :wikipedia:`DMARC`:: > > - From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>" > > + From: "xxx via lists.openembedded.org <xxx@lists.openembedded.org>" > > Please keep this one (or use an example that exists in the wild, I don't > think Linus sent patches to OE-Core :)) as it is an actual example. Okay. > > This ``From`` field is used by ``git am`` to recreate commits with the right > > author name. The following will ensure that your e-mails have an additional > > @@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional > > maintainers accepting your patches don't have to fix commit author information > > manually:: > > - $ git config --global sendemail.from "linus.torvalds@kernel.org" > > + $ git config --global sendemail.from "<email>" > > The ``sendemail.from`` should match your ``user.email`` setting, > > which appears in the ``Signed-off-by`` line of your commits. > > diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst > > index 0f6e9d1d7e85..8412c997a51e 100644 > > --- a/documentation/dev-manual/debugging.rst > > +++ b/documentation/dev-manual/debugging.rst > > @@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard`` > > Makefile target. Here is some abbreviated, sample output with the > > missing dependency clearly visible at the end:: > > - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... > > + i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot> > > . > > . > > . > > @@ -1114,11 +1114,11 @@ debugger. > > After running gdbserver on the target, you need to run Gdb on the > > host and configure it and connect to the target. Use these commands:: > > - $ cd directory-holding-the-debugfs-directory > > - $ arch-gdb > > + $ cd <debugfs-directory> > > + $ <arch>-gdb > > (gdb) set sysroot debugfs > > (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug > > - (gdb) target remote IP-of-target:1234 > > + (gdb) target remote <IP-of-target>:1234 > > Here's yet another prompt we should support that I don't think it's > supported in patch 2/8. Agreed! Good catch. > > At this > > point, everything should automatically load (i.e. matching binaries, > > diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst > > index 77a11fe27047..48f9e7485d93 100644 > > --- a/documentation/migration-guides/migration-5.2.rst > > +++ b/documentation/migration-guides/migration-5.2.rst > > @@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was > > removed from BitBake, which means the following syntax is not supported > > anymore:: > > - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY" > > - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" > > - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy" > > + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>" > > + SRCREV_<nameX> = "<revisionX>" > > + SRCREV_<nameY> = "<revisionY>" > > We should say that this is the full sha of the commit. Sounds good. I thought "revisionX" was better enough from "xxxx", but SHA is better yet. > > This was rarely used in the core repositories because it would only ever make > > sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes > > @@ -205,10 +205,10 @@ places. > > If one of your recipes is using this mechanism, you can split the code source > > fetching into two separate entries:: > > - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \ > > - git://some.host/somepath;bareclone=1;branch=branchY;name=nameY" > > - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" > > - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy" > > + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \ > > + git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>" > > + SRCREV_<nameX> = "<revisionX>" > > + SRCREV_<nameY> = "<revisionY>" > > Ditto. Got it. > Cheers, > Quentin
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst index e60f8ca7ace3..a283eb734768 100644 --- a/documentation/contributor-guide/submit-changes.rst +++ b/documentation/contributor-guide/submit-changes.rst @@ -62,8 +62,8 @@ on Debian and Ubuntu:: Then, you need to set a name and e-mail address that Git will use to identify your commits:: - $ git config --global user.name "Ada Lovelace" - $ git config --global user.email "ada.lovelace@gmail.com" + $ git config --global user.name "<name>" + $ git config --global user.email "<email>" By default, Git adds a signature line at the end of patches containing the Git version. We suggest to remove it as it doesn't add useful information. @@ -399,8 +399,8 @@ regular STMP server, using a Google Mail account as an example:: $ git config --global sendemail.smtpserver smtp.gmail.com $ git config --global sendemail.smtpserverport 587 $ git config --global sendemail.smtpencryption tls - $ git config --global sendemail.smtpuser ada.lovelace@gmail.com - $ git config --global sendemail.smtppass = XXXXXXXX + $ git config --global sendemail.smtpuser <email> + $ git config --global sendemail.smtppass <password> These settings will appear in the ``.gitconfig`` file in your home directory. @@ -509,7 +509,7 @@ We have a frequent issue with contributors whose patches are received through a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is a typical example for people sending from a domain name with :wikipedia:`DMARC`:: - From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>" + From: "xxx via lists.openembedded.org <xxx@lists.openembedded.org>" This ``From`` field is used by ``git am`` to recreate commits with the right author name. The following will ensure that your e-mails have an additional @@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional maintainers accepting your patches don't have to fix commit author information manually:: - $ git config --global sendemail.from "linus.torvalds@kernel.org" + $ git config --global sendemail.from "<email>" The ``sendemail.from`` should match your ``user.email`` setting, which appears in the ``Signed-off-by`` line of your commits. diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 0f6e9d1d7e85..8412c997a51e 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard`` Makefile target. Here is some abbreviated, sample output with the missing dependency clearly visible at the end:: - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... + i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot> . . . @@ -1114,11 +1114,11 @@ debugger. After running gdbserver on the target, you need to run Gdb on the host and configure it and connect to the target. Use these commands:: - $ cd directory-holding-the-debugfs-directory - $ arch-gdb + $ cd <debugfs-directory> + $ <arch>-gdb (gdb) set sysroot debugfs (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug - (gdb) target remote IP-of-target:1234 + (gdb) target remote <IP-of-target>:1234 At this point, everything should automatically load (i.e. matching binaries, diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst index 77a11fe27047..48f9e7485d93 100644 --- a/documentation/migration-guides/migration-5.2.rst +++ b/documentation/migration-guides/migration-5.2.rst @@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was removed from BitBake, which means the following syntax is not supported anymore:: - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY" - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy" + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>" + SRCREV_<nameX> = "<revisionX>" + SRCREV_<nameY> = "<revisionY>" This was rarely used in the core repositories because it would only ever make sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes @@ -205,10 +205,10 @@ places. If one of your recipes is using this mechanism, you can split the code source fetching into two separate entries:: - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \ - git://some.host/somepath;bareclone=1;branch=branchY;name=nameY" - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy" + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \ + git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>" + SRCREV_<nameX> = "<revisionX>" + SRCREV_<nameY> = "<revisionY>" Git fetcher: Branch parameter now required in :term:`SRC_URI` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -216,7 +216,7 @@ Git fetcher: Branch parameter now required in :term:`SRC_URI` The ``branch`` parameter is now required when specifying a Git repository in :term:`SRC_URI`, for example:: - SRC_URI = "git://some.host/somepath;branch=branchX" + SRC_URI = "git://<some.host>/<somepath>;branch=<branchX>" A missing ``branch`` parameter used to produce a warning, and will now produce an error. diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst index 4aa95d8e0499..62c3b707b9ff 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst @@ -474,7 +474,7 @@ This is roughly equivalent to the ``devtool update-recipe`` command followed by the ``devtool reset`` command. The changes must have been committed to the git repository created by ``devtool``. Here is an example:: - $ devtool finish recipe /path/to/custom/layer + $ devtool finish <recipe> <path/to/custom/layer> .. _devtool-building-your-recipe: diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 3c921c3f8087..0072992b8597 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -162,7 +162,7 @@ system and gives an overview of their function and contents. ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. ARCHIVER_MODE[src] = "configured" # Uses configured source files. ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch. - ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff. + ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff. ARCHIVER_MODE[dumpdata] = "1" # Uses environment data. ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
Values the reader is expected to replace are written as though they were literal. "arch-gdb" reads like a command that exists, a Git SRC_URI example reads like a URL and a pair of revisions worth copying, and the git-config examples give an account name and address that are somebody else's. Put them in the angle brackets the manuals already use for the purpose. Two corrections go with them: the directory placeholder in the GDB example described itself at length rather than naming the thing, and the smtppass example carried a stray "=". Since git config takes a name and then a value, that "=" was the value, and the password behind it an argument git config reads as a pattern. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner <twoerner@gmail.com> --- changes in v2: - rebased on master-next; no other change --- .../contributor-guide/submit-changes.rst | 12 ++++++------ documentation/dev-manual/debugging.rst | 8 ++++---- documentation/migration-guides/migration-5.2.rst | 16 ++++++++-------- documentation/ref-manual/devtool-reference.rst | 2 +- documentation/ref-manual/variables.rst | 2 +- 5 files changed, 20 insertions(+), 20 deletions(-)