[Openembedded-architecture] Notes from the OEDAM "Naming Table"

[Richard Purdie]

On Fri, 2016-09-02 at 11:44 -0700, Behan Webster wrote:
> It was done locally over lunch. It would have been good to have you 
> there in person at the "naming table". But the reason it was done 
> with a smaller group offline was purely because not everyone present 
> at the meeting wanted to discuss it. The offline discussion was to 
> come up with some ideas and then post them for all to see and
> discuss.
> 
> I apologize that this caused frustration. Please believe me that this
> was not the intention.

There were people at that discussion who specifically told me that my
input on this topic was not welcome or relevant. I know why they said
this and what they're trying to do but anyhow, you're asking so I will
give some feedback.

> Your input is being asked for now, and indeed is appreciated. The 
> intention was always to involve you.

Not everyone's intention from what I read on irc privately but...

> > I'd mention the following:
> > 
> > a) I am well aware that some people struggle with the naming.
> Sadly, it's not only "some people". The vast majority of people are 
> struggling. I've had to explain this to countless people, and it is
> painful.
> 
> During the YP devday we had in Fremont we had a "meet the developers"
> kind of open mic session. It ended up primary as everyone present 
> complaining about the naming issue to the 5 poor souls at the front 
> of the room (all OE and YP contributors and I believe all people
> subscribed to this mailing list).
> 
> I can't stress enough that this is not a small issue. It is probably 
> the most frustrating non-technical thing people complain to me about
> using YP.

Having witnessed this at least once, I do think that this topic is
sometimes set up for failure though as once you start digging, you
can't stop. Even below, you conflict in what you say and you're drawing
attention to the wrong areas. If this was just a "poky" problem it
would be comparatively easy to solve but I think it is wider than that.
People are being given different, slightly conflicting stories and that
is more the problem and why people get confused. I don't think you
actually understand which pieces of this to emphasis or why we're doing
certain things. I'll try and explain that below.

I also think the biggest problem is the Yocto Project website itself.
I'm on record as stating its *dire* and urgently needing redoing, I
just wish I could find the right people/time/skills to make that
happen.

> > c) Different components do need different names. If we call
> > everything
> > "fish", nobody knows what you're talking about any more. So
> > different
> > names are good. It can't all be "Yocto Project" or "OpenEmbedded"
> > or
> > "Bitbake", they all refer to different very specific things.
> The naming that is being talked about is the "poky" part, 
> specifically the git repo and release tarball.
> 
> Nobody is suggesting the renaming of Yocto, OE or bitbake.

Its more than just poky though, its the version numbers across large
parts of the project, the branch naming and so on. I've heard people
seriously suggest we should drop various names of components, which
would then leave a problem of what to call certain things.

> > d) We could and IMO should relax a bit about some of the incorrect
> > usages. You don't need to correct every misuse of a term, you can
> > generally understand what people are talking about and people do
> > naturally end up learning the correct definitions over time, much
> > like
> > most other natural language development in a new field.
> I agree that one doesn't have to correct the wording of someone's 
> question before answering it.
> 
> However if terms are regularly being misused (as they are) it points 
> to the very problem that started this email thread: that there is a 
> lot of confusion surrounding naming.

For example, if someone says "I'm using Yocto", there will be someone
along to jump on that. Personally, I'm not that bothered about that
slight misuse, there are bigger other things I'd rather fix.

> > e) I don't think we need to present new users with this complete
> > confusing glossary and explanations. I think some things should be
> > mentioned but they don't need the gory details. There are some
> > things
> > you're telling people which shouldn't even exist any more.
> Which things shouldn't be mentioned anymore? Please elaborate.
> 
> > Following on from e), if I'd been part of this discussion, you'd
> > know
> > that I've been trying to kill the poky version number for a while
> > and
> > it should be well and truly dead by now.
> Excellent! That is great to hear.
> 
> >   If its not, I will try and
> > further help eradicate it, just point me at where its still being
> > used.
> https://www.yoctoproject.org/downloads
> 
> All the YP releases are released as tarballs labeled with poky
> release 
> numbers instead of the YP release number.
> 
> YP Core - Krogoth 2.1.1  -> poky-krogoth-15.0.1.tar.bz2

Firstly, I believe the website should be burnt to the ground. I think I
said that in my previous reply too.

Secondly, we don't recommend anyone download and use release tarballs
in our instructions any more and haven't for several years. They're
really just a release artefact and we recommend people clone git
branches.

The reason we have the issue with the poky tarballs specifically is
that poky 1.0, 2.0, 3.0, 3.1, 3.2, 4.0, and 5.0 and a load of point
releases actually exist:

http://downloads.yoctoproject.org/releases/poky/

Those releases predate the Yocto Project or the newer "Yocto Project"
version numbers. To deal with this we basically buried the poky tarball
version numbers. I don't think any user following any of our
instructions should find them any more. The downloads page is one
exception and probably something we should just cull. Since we can't
fix it nicely, the idea is to make it something the user doesn't see or
need to care about. Nobody should be using these tarballs, they're
release artefacts only. The numbers no longer appear in the metadata
itself.

> The idea with release codenames is that typically they are used prior
> to an actual version number being chosen. But instead of using the YP
> release number, we label the tarball with the codename, and the poky 
> version number?

So, forget those tarballs and lets talk about the codenames. These are
not "prior to the version number being chosen", there is a much more
specific issue they address and this is important.

How do you tell which branch of layer X is meant to work with which
branch of layer Y? Everyone likes to number their releases. Intel wants
to number its releases one way, TI another and so on. We cannot expect
to control this as there are business needs on why some layer will want
point releases, some were using OE prior to the Yocto Project and so
on. Nobody will ever agree on numbers.

The solution is the codenames. These are chosen so that a given release
has a specific name associated with it and they're fairly distinctive
so "krogoth" in meta-intel clearly is designed to work with "krogoth"
in OE-Core. So the names are *way* more important that the version
number.

The one downside to the codenames is the lack of sorting. I am trying
to at least sort the names a bit now at the expense of a bit less fun
with the naming themes (fido, jethro, krogoth all follow
alphabetically). The codenames are also intentionally a little quirky,
it also helps them be a little distinctive and recognisable and I
believe we do need to have a sense of humour too.

Of course some people are allergic to the codenames for a variety of
reasons so the YP does pick a version number for the release too and we
can't drop that for various reasons better explained over beer. The
codename however is the key, the number is less relevant. This is what
we need to promote to the users.

> On a separate, but related note, we also then suggest that people
> clone 
> YP 2.1.1 from git using the codename "krogoth", instead of the YP 
> release number.

See above, this is backwards. We recommend people clone the krogoth
branch of the relevant project layers. The point releases are points
where we validate and put those branches through specific testing and
tag them as such. What can we tag them with? A point release number.
What else have we got to use?

Think about Intel releasing BSP version 2.3, TI releasing version 1.5
and both work with YP 2.1. It'd be a nightmare to use numbers for the
branches.

> It sounds to me that we all have the same goal of making things
> clearer.

That is true.

I'm sorry if I sound a bit weary, trying to sort out the M3 feature
freeze point is the most stressful point in the release cycle. I've
also been around and around on this discussion many times. I have tried
to do what I can to improve things (e.g. culling the poky version
number except for the tarballs themselves which were meant to be moved
out of sight). The next biggest thing I think we can probably do is the
YP website itself as I think that is generating a lot of the confusion.

Cheers,

Richard