On Wed, 15 Jul 2020 at 06:31, Trevor Woerner <twoerner@...> wrote:

Hi,

As most are aware, there are efforts in many open-source/free-software
communities to adjust the language that is used throughout a given project
to be more inclusive.

We discussed this briefly at the most recent YP Technical Team/Engineering
Sync Meeting. Many good points were raised. I'd like to start a discussion on
this topic via email in order to enumerate and keep track of these efforts.

1. As a project we need to decide whether or not to undertake this work. Not
all projects have decided to make any changes. The discussions we had at the
last meeting made it feel as though it was a forgone conclusion by those who
spoke up that we would take on this work. Is that the consensus? Silence
represents agreement?

Review comments will likely appear when patches are submitted.

On that note, I recommend we move the coding style documentation from
the wiki into the oe-core git repository so that changes can be
reviewed in the normal way. Right now it's at
https://www.openembedded.org/wiki/Styleguide and
https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines
which have no review process for changes and are often missed by new
contributors who don't know where to find them.

2. Scope Creep. From the dawn of the OE project, there have been "discussions"
around variable/function names. In order to keep this work sane and concise, I
must insist that the scope of this work is "inclusive language" not "PN is too
cryptic for beginners, we should expand it to PACKAGENAME"

Agreed. Also, we should focus on Bitbake and OpenEmbedded terminology,
we can't fix the terminology of all packages for which we have
recipes.

3. Deprecation Plan. Given the layered nature of the ecosystem, inevitably
there will be not-so-frequently-used layers out there that could stop working
entirely depending on how this work is implemented. Do we continue to support
the "old" language indefinitely? Do we have a flag day where everything
changes at once? Do we give warnings for X releases then have a cut off?

I recommend we introduce new terminology with backwards-compatible
aliases in the 3.2 release if possible, 3.3 if not. Some magic may be
needed for variable flags if we rename PNBLACKLIST. At this point the
documentation should use new terminology with old naming used only in
a migration guide.

Backwards-compatible aliases should be removed in release N+1 or even
N+2 if necessary.

4. What will be affected? Branch names, variable names, function names,
fetchers, patch file names, documentation… Given the fact we build code from
upstream projects, if we currently build from an upstream's master branch and
that upstream project never changes the name of their main branch away from
"master", I don't think there's anything we can do in those cases.

Let's focus on terminology introduced by Bitbake and OpenEmbedded
itself. That should be enough to get us started, if we want to change
anything else we can do that in a later phase.

5. Backports. How far back do we make changes?

We should leave existing releases as-is.

6. Terminology. The Linux kernel project has put out some recommendations:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb

I think this is an excellent list.

Note that it doesn't say anything about the use of 'master' alone
without corresponding 'slave' terminology. GitHub has championed using
'main' instead of 'master', personally I'd prefer 'dev' as it's more
descriptive of the status but this is how bikeshedding begins. I
recommend we start by adopting the changes in the kernel commit above,
if we want to rename 'master' we can do that in a later phase.

To start the discussion, can we please get a consensus on item #1? If
positive, can we then work on whether we agree with the list of items (have I
forgotten anything, are there things to add to the list, or things to remove
from the list)? THEN can we please focus on each of the items from the list we
create?

I recommend we start by having someone submit a patch to add a coding
style document to the oe-core repository. That can be reviewed in the
usual way. We can then proceed to implement the new coding style in a
backwards compatible way over the next few months as development
resources permit.

I think that would be a more sane approach rather than trying to do everything
at once.

Best regards,
Trevor

--
Paul Barker
Konsulko Group