[poky] [PATCH] README.poky: Update to switch to markdown format and update

[poky] [PATCH] README.poky: Update to switch to markdown format and update

[Richard Purdie]

[-- Attachment #1: Type: text/plain, Size: 514 bytes --]

Mentioning on the docs list.

I a plan is forming to migrate the various READMEs in the repos to markdown
format and display these in the git web interface in the about page. If this
merges I'll work with MichaelH to make sure it displays properly on the
about page.

I've had a go at improving the poky one which needed a bit of modernisation
anyway. Help with others welcome.

I am a little torn on this as it does make the README harder to read
outside of rendered interfaces.

Cheers,

Richard

[-- Attachment #2: Forwarded message — [poky] [PATCH] README.poky: Update to switch to markdown format and update --]
[-- Type: message/rfc822, Size: 15383 bytes --]

[-- Attachment #2.1.1: Type: text/plain, Size: 6978 bytes --]

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 README.poky => README.poky.md |  0
 meta-poky/README.poky         | 77 ++++++++++++++---------------------
 2 files changed, 30 insertions(+), 47 deletions(-)
 rename README.poky => README.poky.md (100%)

diff --git a/README.poky b/README.poky.md
similarity index 100%
rename from README.poky
rename to README.poky.md
diff --git a/meta-poky/README.poky b/meta-poky/README.poky
index be0c6c016e0..02b46327094 100644
--- a/meta-poky/README.poky
+++ b/meta-poky/README.poky
@@ -1,35 +1,19 @@
-Poky
-====
+#Poky
 
-Poky is an integration of various components to form a complete prepackaged
-build system and development environment. It features support for building
-customised embedded device style images. There are reference demo images
-featuring a X11/Matchbox/GTK themed UI called Sato. The system supports
-cross-architecture application development using QEMU emulation and a
-standalone toolchain and SDK with IDE integration.
+Poky is an integration of various components to form pre-packaged build system and development environment which is used as a development and validation tool by the [Yocto Project](http://www.yoctoproject.org/ "Yocto Project"). It features support for building customised embedded style device images and custom containers. There are reference demo images ranging from X11/GTK+ to Weston, commandline and more. The system supports cross-architecture application development using QEMU emulation and a standalone toolchain and SDK suitable for IDE integration.
 
-Additional information on the specifics of hardware that Poky supports
-is available in README.hardware. Further hardware support can easily be added
-in the form of layers which extend the systems capabilities in a modular way.
+Additional information on the specifics of hardware that Poky supports is available in README.hardware. Further hardware support can easily be added in the form of BSP layers which extend the systems capabilities in a modular way. Many layers are available and can be found through the [layer index](https://layers.openembedded.org/ "layer index").
 
-As an integration layer Poky consists of several upstream projects such as 
-BitBake, OpenEmbedded-Core, Yocto documentation and various sources of information 
-e.g. for the hardware support. Poky is in turn a component of the Yocto Project.
+As an integration layer Poky consists of several upstream projects such as  [BitBake](https://git.openembedded.org/bitbake/ "BitBake"), [OpenEmbedded-Core](https://git.openembedded.org/openembedded-core/ "OpenEmbedded-Core"), [Yocto documentation](http://git.yoctoproject.org/cgit.cgi/yocto-docs/ "Yocto documentation"), the '[meta-yocto](http://git.yoctoproject.org/cgit.cgi/meta-yocto/ "meta-yocto")' layer which has configuration and hardware support components. These components are all part of the Yocto Project and OpenEmbedded ecosystems.
 
-The Yocto Project has extensive documentation about the system including a 
-reference manual which can be found at:
-    http://yoctoproject.org/documentation
+The Yocto Project has extensive documentation about the system including a  reference manual which can be found at  https://docs.yoctoproject.org/
 
-OpenEmbedded-Core is a layer containing the core metadata for current versions
-of OpenEmbedded. It is distro-less (can build a functional image with
-DISTRO = "") and contains only emulated machine support.
+OpenEmbedded is the build architecture used by Poky and the Yocto project.
+For information about OpenEmbedded, see the [OpenEmbedded website](http://www.openembedded.org/ "OpenEmbedded website").
 
-For information about OpenEmbedded, see the OpenEmbedded website:
-    http://www.openembedded.org/
+#Contribution Guidelines
 
-
-Contribution Guidelines
-=======================
+The project works using a mailing list patch submission process. Patches should be sent to the mailing list for the repository the components originate from (see below). Throughout the Yocto Project, the README files in the component in question should detail where to send patches, who the maintainers are and where bugs should be reported.
 
 A guide to submitting patches to OpenEmbedded is available at:
 
@@ -40,32 +24,31 @@ There is good documentation on how to write/format patches at:
 https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines
 
 
-Where to Send Patches
-=====================
+#Where to Send Patches
+
+As Poky is an integration repository (built using a tool called combo-layer), patches against the various components should be sent to their respective upstreams:
+
+OpenEmbedded-Core (files in meta/, meta-selftest/, meta-skeleton/, scripts/):
+
+- Git repository: https://git.openembedded.org/openembedded-core/
+-  Mailing list: openembedded-core@lists.openembedded.org
+
+BitBake (files in bitbake/):
+
+- Git repository: https://git.openembedded.org/bitbake/
+- Mailing list: bitbake-devel@lists.openembedded.org
 
-As Poky is an integration repository (built using a tool called combo-layer),
-patches against the various components should be sent to their respective
-upstreams:
+Documentation (files in documentation/):
 
-bitbake:
-    Git repository: http://git.openembedded.org/bitbake/
-    Mailing list: bitbake-devel@lists.openembedded.org
+- Git repository: https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/
+- Mailing list: docs@lists.yoctoproject.org
 
-documentation:
-    Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/
-    Mailing list: docs@lists.yoctoproject.org
+meta-yocto (files in meta-poky/, meta-yocto-bsp/):
 
-meta-poky, meta-yocto-bsp:
-    Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto(-bsp)
-    Mailing list: poky@lists.yoctoproject.org
+- Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto
+- Mailing list: poky@lists.yoctoproject.org
 
-Everything else should be sent to the OpenEmbedded Core mailing list.  If in
-doubt, check the oe-core git repository for the content you intend to modify.
-Before sending, be sure the patches apply cleanly to the current oe-core git
-repository.
+If in doubt, check the openembedded-core git repository for the content you intend to modify as most files are from there unless clearly one of the above categories. Before sending, be sure the patches apply cleanly to the current git repository branch in question.
 
-    Git repository: http://git.openembedded.org/openembedded-core/
-    Mailing list: openembedded-core@lists.openembedded.org
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/765/badge)](https://bestpractices.coreinfrastructure.org/projects/765)
 
-Note: The scripts directory should be treated with extra care as it is a mix of
-oe-core and poky-specific files from meta-poky.
-- 
2.30.2

\r

[-- Attachment #2.1.2: Type: text/plain, Size: 400 bytes --]


-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#12461): https://lists.yoctoproject.org/g/poky/message/12461
Mute This Topic: https://lists.yoctoproject.org/mt/83372875/1686473
Group Owner: poky+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/poky/unsub [richard.purdie@linuxfoundation.org]
-=-=-=-=-=-=-=-=-=-=-=-

Re: [docs] [poky] [PATCH] README.poky: Update to switch to markdown format and update

[Quentin Schulz]

Hi Richard,

On Mon, Jun 07, 2021 at 04:36:22PM +0100, Richard Purdie wrote:
> Mentioning on the docs list.
> 
> I a plan is forming to migrate the various READMEs in the repos to markdown
> format and display these in the git web interface in the about page. If this

Does it need to be in MarkDown format to be displayed in the About
section?

> merges I'll work with MichaelH to make sure it displays properly on the
> about page.
> 
> I've had a go at improving the poky one which needed a bit of modernisation
> anyway. Help with others welcome.
> 

Anyway to have those two changes separate so we can properly review each
separately?

> I am a little torn on this as it does make the README harder to read
> outside of rendered interfaces.
> 

But it'd be displayed correctly in the Github mirror and Gitlab for
those using it I guess.

Most projects hosted on Github/Gitlab use MarkDown so I don't think it's
such a bad idea, I'm just not sure it has as much benefit on cgit since
it's not the landing page of the repo (the summary page is).

If we can display the non-MD version in the about page, I don't think
there's a huge benefit of migrating to MD?

If we absolutely need MD for the about page, go for it as it'll cover
Github, Gitlab and probably others.

We might want to modify bitbake-layers create-layer to provide a
README.md too instead of the current template?

Cheers,
Quentin

Re: [docs] [poky] [PATCH] README.poky: Update to switch to markdown format and update

[Richard Purdie]

On Mon, 2021-06-07 at 17:59 +0200, Quentin Schulz wrote:
> Hi Richard,
> 
> On Mon, Jun 07, 2021 at 04:36:22PM +0100, Richard Purdie wrote:
> > Mentioning on the docs list.
> > 
> > I a plan is forming to migrate the various READMEs in the repos to markdown
> > format and display these in the git web interface in the about page. If this
> 
> Does it need to be in MarkDown format to be displayed in the About
> section?

No, but it does help a little and see below.

> > merges I'll work with MichaelH to make sure it displays properly on the
> > about page.
> > 
> > I've had a go at improving the poky one which needed a bit of modernisation
> > anyway. Help with others welcome.
> > 
> 
> Anyway to have those two changes separate so we can properly review each
> separately?

I can reverse engineer them back apart I guess, I just couldn't bring myself
to leave it as it was as it needed reformatting and so on anyway.

> > I am a little torn on this as it does make the README harder to read
> > outside of rendered interfaces.
> > 
> 
> But it'd be displayed correctly in the Github mirror and Gitlab for
> those using it I guess.
> 
> Most projects hosted on Github/Gitlab use MarkDown so I don't think it's
> such a bad idea, I'm just not sure it has as much benefit on cgit since
> it's not the landing page of the repo (the summary page is).
> 
> If we can display the non-MD version in the about page, I don't think
> there's a huge benefit of migrating to MD?
> 
> If we absolutely need MD for the about page, go for it as it'll cover
> Github, Gitlab and probably others.
> 
> We might want to modify bitbake-layers create-layer to provide a
> README.md too instead of the current template?

There is the issue of needing to display a best practices badge somewhere
for the project which only really makes sense in markdown format which
kind of pushed me into this.

Cheers,

Richard

Re: [docs] [poky] [PATCH] README.poky: Update to switch to markdown format and update

[Quentin Schulz]

Hi Richard,

On Mon, Jun 07, 2021 at 05:16:43PM +0100, Richard Purdie wrote:
> On Mon, 2021-06-07 at 17:59 +0200, Quentin Schulz wrote:
> > Hi Richard,
> > 
> > On Mon, Jun 07, 2021 at 04:36:22PM +0100, Richard Purdie wrote:
> > > Mentioning on the docs list.
> > > 
> > > I a plan is forming to migrate the various READMEs in the repos to markdown
> > > format and display these in the git web interface in the about page. If this
> > 
> > Does it need to be in MarkDown format to be displayed in the About
> > section?
> 
> No, but it does help a little and see below.
> 
> > > merges I'll work with MichaelH to make sure it displays properly on the
> > > about page.
> > > 
> > > I've had a go at improving the poky one which needed a bit of modernisation
> > > anyway. Help with others welcome.
> > > 
> > 
> > Anyway to have those two changes separate so we can properly review each
> > separately?
> 
> I can reverse engineer them back apart I guess, I just couldn't bring myself
> to leave it as it was as it needed reformatting and so on anyway.
> 

The constant struggle of trying not to fix everything at once in the
docs :)

> > > I am a little torn on this as it does make the README harder to read
> > > outside of rendered interfaces.
> > > 
> > 
> > But it'd be displayed correctly in the Github mirror and Gitlab for
> > those using it I guess.
> > 
> > Most projects hosted on Github/Gitlab use MarkDown so I don't think it's
> > such a bad idea, I'm just not sure it has as much benefit on cgit since
> > it's not the landing page of the repo (the summary page is).
> > 
> > If we can display the non-MD version in the about page, I don't think
> > there's a huge benefit of migrating to MD?
> > 
> > If we absolutely need MD for the about page, go for it as it'll cover
> > Github, Gitlab and probably others.
> > 
> > We might want to modify bitbake-layers create-layer to provide a
> > README.md too instead of the current template?
> 
> There is the issue of needing to display a best practices badge somewhere
> for the project which only really makes sense in markdown format which
> kind of pushed me into this.
> 

It's all settled then :)

MarkDown is not that much less readable than plain text anyway, it can easily
be picked up by anyone, so no objection on my part. LGTM.

Cheers,
Quentin

Re: [poky] [PATCH] README.poky: Update to switch to markdown format and update

[Richard Purdie]

On Tue, 2021-06-08 at 09:53 +0100, Paul Barker wrote:
> I've given this a quick review for markdown usage, hopefully some of
> these comments are useful. I recommend checking with
> https://github.com/markdownlint/markdownlint to help find subtle
> syntax errors which might trip up the rendering.
> 
> On Mon, 7 Jun 2021 at 16:30, Richard Purdie
> <richard.purdie@linuxfoundation.org> wrote:
> > --- a/meta-poky/README.poky
> > +++ b/meta-poky/README.poky
> > @@ -1,35 +1,19 @@
> > -Poky
> > -====
> > +#Poky
> 
> Underlining with = characters is still supported for h1 headings if
> this is preferred.

Thanks all for the review. I've sent a v2 which hopefully addresses
the feedback (and passes the linter apart from some white space I left
as it made the diff more readable).

Cheers,

Richard

Re: [poky] [PATCH] README.poky: Update to switch to markdown format and update

[Paul Barker]

I've given this a quick review for markdown usage, hopefully some of
these comments are useful. I recommend checking with
https://github.com/markdownlint/markdownlint to help find subtle
syntax errors which might trip up the rendering.

On Mon, 7 Jun 2021 at 16:30, Richard Purdie
<richard.purdie@linuxfoundation.org> wrote:
> --- a/meta-poky/README.poky
> +++ b/meta-poky/README.poky
> @@ -1,35 +1,19 @@
> -Poky
> -====
> +#Poky

Underlining with = characters is still supported for h1 headings if
this is preferred.

>
> -Poky is an integration of various components to form a complete prepackaged
> -build system and development environment. It features support for building
> -customised embedded device style images. There are reference demo images
> -featuring a X11/Matchbox/GTK themed UI called Sato. The system supports
> -cross-architecture application development using QEMU emulation and a
> -standalone toolchain and SDK with IDE integration.
> +Poky is an integration of various components to form pre-packaged build system and development environment which is used as a development and validation tool by the [Yocto Project](http://www.yoctoproject.org/ "Yocto Project"). It features support for building customised embedded style device images and custom containers. There are reference demo images ranging from X11/GTK+ to Weston, commandline and more. The system supports cross-architecture application development using QEMU emulation and a standalone toolchain and SDK suitable for IDE integration.

You should be able to hard wrap these lines at a reasonable length in
the source file and they should still be rendered into a single nicely
flowed paragraph by most markdown processors.

>
> -Additional information on the specifics of hardware that Poky supports
> -is available in README.hardware. Further hardware support can easily be added
> -in the form of layers which extend the systems capabilities in a modular way.
> +Additional information on the specifics of hardware that Poky supports is available in README.hardware. Further hardware support can easily be added in the form of BSP layers which extend the systems capabilities in a modular way. Many layers are available and can be found through the [layer index](https://layers.openembedded.org/ "layer index").

The link title is intended to be rendered as a tooltip when hovering
over the link so it's not needed unless it adds extra information. See
the example in https://www.markdownguide.org/basic-syntax/#adding-titles.
So this could just be [layer index](https://layers.openembedded.org/).
The same applies for other links below.

>
> -As an integration layer Poky consists of several upstream projects such as
> -BitBake, OpenEmbedded-Core, Yocto documentation and various sources of information
> -e.g. for the hardware support. Poky is in turn a component of the Yocto Project.
> +As an integration layer Poky consists of several upstream projects such as  [BitBake](https://git.openembedded.org/bitbake/ "BitBake"), [OpenEmbedded-Core](https://git.openembedded.org/openembedded-core/ "OpenEmbedded-Core"), [Yocto documentation](http://git.yoctoproject.org/cgit.cgi/yocto-docs/ "Yocto documentation"), the '[meta-yocto](http://git.yoctoproject.org/cgit.cgi/meta-yocto/ "meta-yocto")' layer which has configuration and hardware support components. These components are all part of the Yocto Project and OpenEmbedded ecosystems.
>
> -The Yocto Project has extensive documentation about the system including a
> -reference manual which can be found at:
> -    http://yoctoproject.org/documentation
> +The Yocto Project has extensive documentation about the system including a  reference manual which can be found at  https://docs.yoctoproject.org/

Raw URLs usually render ok but proper syntax is to surround them in
angle brackets like <https://docs.yoctoproject.org/>.

>
> -OpenEmbedded-Core is a layer containing the core metadata for current versions
> -of OpenEmbedded. It is distro-less (can build a functional image with
> -DISTRO = "") and contains only emulated machine support.
> +OpenEmbedded is the build architecture used by Poky and the Yocto project.
> +For information about OpenEmbedded, see the [OpenEmbedded website](http://www.openembedded.org/ "OpenEmbedded website").
>
> -For information about OpenEmbedded, see the OpenEmbedded website:
> -    http://www.openembedded.org/
> +#Contribution Guidelines
>
> -
> -Contribution Guidelines
> -=======================

These should be h2 headings which can be achieved by underlining with
- characters or using two hashes. Documents render best with just one
h1 heading at the top level.

Thanks,

-- 
Paul Barker
Konsulko Group