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

[Behan Webster]

On 2016-09-02 03:37 PM, Richard Purdie wrote:
>> 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...
*sigh*

I can assure you that it was very clear at the "naming table" that the 
notes would be published here, and explicitly you (amongst others) would 
be consulted. I don't see how anything else would make any sense.

>>> 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.
The website is indeed awful. :(

>>> 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.
At this moment, the discussion is being explicitly pointed at this one 
problem. We started down the road of discussing all naming issues, and 
settled on choosing only one to tackle for the moment.

Indeed there are other things to discuss later on.

>>> 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.
I'm more concerned that people are very confused about the difference 
between yocto/open embedded/poky, and often use them interchangeably. 
Without some clear understanding having different names is essentially 
pointless. Indeed some confusion is excusable, but systemic confusion 
denotes the symptom of a problem.

However, when people are confused from the very start that you download 
a poky tarball or clone the poky repo to build a release of the yocto 
project using the open embedded build system, then we probably should 
think about simplifying things. At least one of those names isn't 
required there.

Both "Yocto Project" and "Open Embedded" are active entities. Poky is 
more of a historical thing which doesn't really exist on its own anymore.

My audience is primarily people new to YP/OE and people who are trying 
to bring YP/OE to their companies and management. And they all have the 
same complaint about trying to explain this stuff to others, and then 
essentially giving up.

>>> 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.
I am still interested in your further input on this question.

>>> 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.
You indeed did. However, this is the release area which, though part of 
the website, is essentially separate from it. It could just as easily be 
a bare FTP site (ew). My naming criticism is still valid beyond the 
specifics of the website.

> 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.
I understand that it is not the recommended way. However, release 
tarballs are published, and are therefore used and/or preferred by some. 
And there are lots of places we bring the Yocto Project where customers 
require a tarball release for their procedure of adopting outside 
source. (Not my requirements, but the requirements of my customers)

git access is also not always an option. Indeed tarring up the git repo 
is a possibility, but that doesn't really bring much value over the 
release tarball.

Sadly I have to teach in lots of places with little to no internet 
access (behind draconian corporate firewalls, and/or highly secured 
classroom networks). And indeed my colleagues have similar stories. This 
means that though we discuss git as being the preferred method, we teach 
from the tarballs.

> 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 understand the historical reasons. But they don't need to dictate what 
is done moving forward.

>   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.
But why ship as "poky" (the repo/tarball name) at all? Why not rename 
the repo/tarball to represent the yocto project release for which it is 
in fact being published?

Poky is now essentially just a meta layer after all. Keeping the repo 
and tarball named "poky" doesn't really provide any value.

>> 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.
Agreed. As I said, typically codenames are typically adopted before 
numbers are assigned. Your use case merely takes that to the next level 
(multiple different release 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.
They indeed seem to solve this specific problem.

> 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.
Indeed. I was going to suggest following a monotonically incrementing 
alphabetic names (like Ubuntu does) which makes codenames a lot easier 
to at least figure out the order of releases, and allows for sorting.

> 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.
I like codenames. I just don't like them being entirely arbitrary. My 
frustration is when they are used inconsistently. As long as we're 
consistent, I'm happy.

>> 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?
Could we not also tag them with the YP release number? Tags are 
effectively free. No reason we can't have both codename and YP release: 
yp-2.1.1

> 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.
I was thinking more using release tags as I said above (much like the 
kernel does things)

I agree that branches shouldn't use version numbers.

>> 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.
No worries. All understood, and appreciated.

As long as we're all on the same page of making things better and just 
negotiating the details, I'm happy.

Thanks,

Behan

-- 
Behan Webster
behanw at converseincode.com