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

Submitted by Richard Purdie on June 7, 2021, 3:36 p.m. | Patch ID: 179877

Details

Message ID 3c7b1f74d4b989316e24be08db75f34720198e2d.camel@linuxfoundation.org
State New
Headers show

Commit Message

Richard Purdie June 7, 2021, 3:36 p.m.
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
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%)

Patch hide | download patch | download mbox

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.

Comments

Quentin Schulz June 7, 2021, 3:59 p.m.
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
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1392): https://lists.yoctoproject.org/g/docs/message/1392
Mute This Topic: https://lists.yoctoproject.org/mt/83373100/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Richard Purdie June 7, 2021, 4:16 p.m.
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
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1393): https://lists.yoctoproject.org/g/docs/message/1393
Mute This Topic: https://lists.yoctoproject.org/mt/83373100/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-