Jenkins Terminology cleanup continued - sub-terms for controllers

[Oleg Nenashev]

Dear all,

As discussed in the Jenkins chats, we would like to continue the terminology definitions we agreed on in 2020. Just to summarize the status from this thread and the related announcements:

• We adopted "controller" as a term to define the main Jenkins instance which acts as a web interface and the Jenkins system controller (context, agent controller, endpoint for CLI and REST API, etc.). Formerly known as "master", yes
• We agreed that localizations for the term are to be reviewed on a case-by-case basis by maintainers and localization leaders. Recommendations for German, French, Spanish, Chinese, Italian and Russian are defined here.
• We agreed to follow-up on the naming for sub-entities of the controller instance: e.g. Web interface, Jenkins as a "main" node, labels, etc. This follow-up has not happened yet...

In this thread I suggest to finally agree on terms for the third item so that we could ensure that all patches use the same terminology. It is VERY important, because such sub-entity terms are widespread in the Jenkins Web UI. For example, a screenshot from Danioel Beck:

I have started a table for sub-entity terms here, this document is open for any suggestions. We kindly invite all interested contributors to:

• Help us identify areas where "controller"/"master" terms need to be amended. These terms might be used inside the Jenkins core or in any other Jenkins components: docs, plugins, etc. Whatever you see, let's fix that
• Come up with term proposals or comment on already proposed ones

Thanks in advance to all contributors!

Best regards,

Oleg Nenashev

Jenkins Governance Board

[Oleg Nenashev]

Dear all,

Thanks to everyone who contributed their ideas in the sub-term definitions list. We've got a number of ideas and identified the missing terms where we need decisions. Most notable ones which require discussion:

• Jenkins as node
  
• Jenkins “main node” label - Aligned with “Jenkins as node”
  
• Jenkins master pod - for K8s components
  
• “Master branch” in documentation, not the repository layout
  

I suggest we continue the discussion and finalize the term decisions at the next governance meeting on May 05. I encourage all contributors to review the doc, vote for terms and let us know if you see any term missing. Hopefully we could build a consensus before th governance meeting happens.

Thanks for your time,

Oleg Nenashev

[Oleg Nenashev]

Based on the current feedback, the following terminology is suggested:

• Master node => "Built-in Node"
• "master" label => "builtin" // We will need to keep master for compatibility reasons, but it can be deprecated and maybe even hidden from UI
  
• “Master branch” in documentation and help => "default branch"
• Agent-to-Master security => " Agent-to-Controller security "
• "Jenkins master container " => "Jenkins controller container"
• "Jenkins master pod" => "Jenkins controller pod" // That still sounds a bit fishy since "controller" is a term in K8s
  
• "Serialization whetelist" for JEP-200 => "serialization permit list"

Any objections regarding these terms?

[Tim Jacomb]

> "Serialization whetelist" for JEP-200 => "serialization permit list"

Any thoughts on allow list rather than permit? Permit sounds a bit funny to me

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/81506cb1-ce85-4ebe-9990-45bc9ae53f7an%40googlegroups.com.

[Oleg Nenashev]

Re allowlistt vs. permitlist, I am happy to follow the suggestion of native speakers

You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/x5vdlJDvntw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAH-3Bic6oatPUT-Uyg1XfULYGeO6g4mLA_Kzwoymxh_VPpbS%3DQ%40mail.gmail.com.

[Tony Noble]

In other projects, I've seen whitelist/blacklist moved to allowlist/denylist, which *should* translate without context, I'd have thought.  permit/block would seem to be the other possible analog.

Tony

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLCvXiMhQ5HCiLPrqisWLyVT2S3fukFzF%3DvXqhLEU3w4yg%40mail.gmail.com.

[Oleg Nenashev]

I agree, let's default to allowlist/denylist unless there is negative feedback

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAEWqh9FHCLv8-k%2BTvkCEwKr%3D9RSjMZS1Zd%3D%2BwNGfESStEjqLpw%40mail.gmail.com.

[Gavin Mogan]

+1 to allow/deny, as tim said, permit just feels...not right

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLAYWXED45vOYpqSK-nGe0mK-r4ZmGofd_O3%3Dc6ryZHaQA%40mail.gmail.com.

[Bartłomiej Antoniak]

+1 to allow/deny list as this is becoming standard 

• "Jenkins master pod" => "Jenkins controller pod" // That still sounds a bit fishy since "controller" is a term in K8s
  

I'd just keep it as Jenkins pod if makes sense. Controllers term is used to watch and reconcile resources so it might be misleading for some people.

Apart from that +1

Regards,

Bartek

[Oleg Nenashev]

Agree about the "Jenkins controller pod", but not sure that "Jenkins pod" would not cause issues.

Assuming that the pod may include not only the controller container but also other containers (e.g. monitoring, storage, ELK, etc.), would it make sense to consider the "Jenkins main pod"? In this case "main" and "controller" may actually mean different things.

Email correspondence is considered personal data processing. Check out our Privacy Policy for details about the controller of your data and your rights according to GDPR/RODO.

--
You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/x5vdlJDvntw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/ef6b43eb-5430-4653-ab33-7e8f9cac131dn%40googlegroups.com.

[Tim Jacomb]

Main sounds weird, Jenkins pod / Jenkins container should be fine

Jenkins controller pod would also work

No strong opinion though 

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLC96nGE8O%3Dc%2BbBjBCmYmJfBdJ8kCHKsJLE0Cwmw61c7Eg%40mail.gmail.com.

[Daniel Beck]

> On 4. May 2021, at 16:59, Oleg Nenashev <o.v.ne...@gmail.com> wrote:
>
> • Master node => "Built-in Node"

To provide a bit of context for this one for those that don't remember from last year :-)

Before, there was no real distinction between "Jenkins master, the process" (mostly) and "Jenkins master, the node". When I worked on the PR in which I started cleaning up the terms, it became apparent a different term could be useful.[1]

A simple example: The built-in node can be offline while the controller is otherwise running.

In some code, the relation between master-specific and global node properties also wasn't clear in some places because both were occasionally called "master" (and only one set is inherited by agents).

There's not a huge list of obvious examples because a lot of the things that could matter are shared (process, file system, config file to an extent) or irrelevant (node launcher).

I still think it would be useful to distinguish in terms between the controller and the built-in node, if only because 'controller' for the node may create wrong associations (it controlling things, rather than "just" being part of the controller process).


However there are also limitations, which make a different term not an obviously correct choice:

- The built-in node is part of the controller process, it shares the controller's file system and OS permissions. If the built-in node is doing work, the controller has load. A lot of resources are shared, so "the built-in node's configuration is stored in the config.xml file with most of the controller configuration on the controller file system" etc.
- People seem to confuse executors and nodes/agents fairly regularly, so may well consider these to be the same thing because the differences are way less relevant than compared to agents, leading to wrong documentation and other advice, possibly confusing those aware of the terms. (It might help that controller as a term is getting rather well established, and that the node will get labels (both UI and environment var) referring to it by its new name, but who knows.)


I encourage you to check out the PR with placeholder term to get a sense for the differences and consider whether you think distinguishing the terms is useful. As the PR is still a draft and uses an obvious placeholder term, please skip doing an actual review for now.

(Note that the behavior-changing code in my PR (related to migration) would be needed anyway, regardless of the term we choose. It's more about removing "master" than what the replacement term is.)


1: https://github.com/jenkinsci/jenkins/pull/5425

[Oleg Nenashev]

Hi all,

We made decisions on a few terms at the yesterday's governance meeting:

• Master node => "Built-in Node"

• "master" label => "built-in" // We will use it unless we discover a technical issue with the hyphen. Then we fallback to “builtin”

• “Master branch” in documentation and help => "default branch"
• Agent-to-Master security => " Agent-to-Controller security "
• "Jenkins master container " => "Jenkins controller container"

• "Serialization whitelist" for JEP-200 => "serialization allowlist"

We also agreed that we will be using "allowlist" in our terminology, not the "permitlist" as it was suggested in a few occasions. We have not finalized decisions on other terms, including the "Jenkins master pod". I raised https://github.com/jenkinsci/kubernetes-operator/issues/561 in the Jenkins operator project to track the change on its side once we agree on the term.

If anyone is interested, I can create a global "terminology cleanup" project in the jenkinsci organization. It will allow tracking pull request better on the GitHub's side

Best regards,

Oleg Nenashev

[Oleg Nenashev]

Do we have any terms we'd like to finalize during the next meeting?

I have also created https://github.com/orgs/jenkinsci/projects/5 to track the related pull requests and to see where any help is needed

[Angélique Jard]

Hello, what do you think about changing terminology in changelogs ? The topic has been raised on Jira comment here:
https://issues.jenkins.io/browse/JENKINS-65398?focusedCommentId=408976&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-408976

I was not doing it because changing the past didn't seems accurate, but I don't have a strong opinion, I would say "why not". Does anyone has some opinion on that ?

(@Oleg: I love that board by the way :D )

[Oleg Nenashev]

My vote is for updating changelogs where possible. Less obsolete terminology entries we have, the better for everyone. Of course retrospectively changing things like whitelisted-classes.txt filename for JEP-200 is not an option. But it is fine to do it where you just have text or Web UI controls. For the latter ones we might need to cleanup documentation and changelogs in parallel with the updates of changelogs.

(@Angélique: thanks :P)

--
You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/x5vdlJDvntw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/ff3dbd9b-8f7d-476f-ad09-153d4435fb52n%40googlegroups.com.

[Mark Waite]

I like the idea of updating changelogs where possible, though it may be more complicated than pure text replacement, especially when a string is used to describe something from the user interface.

You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLBQ_MvAUyGKqA_bDN5bAdC%3D2YPUsz4apHrccNmZkaQvTw%40mail.gmail.com.

[Gavin Mogan]

I'm actually against updating the changelog. The changes to terminology were not done then, and by showing the old and the new, you show growth. I'm not a fan of rewriting history, even in git.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAO49JtEaCx2P5GsuRp0s78uLXa7M3V-V08ZD5vCdg0pAC5EeLA%40mail.gmail.com.

[tony....@gmail.com]

Seconded.  Think it’s better to explain why the terminology was changed than to pretend it never happened.

On 19 May 2021, at 07:08, 'Gavin Mogan' via Jenkins Developers <jenkin...@googlegroups.com> wrote:



To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAG%3D_DutAmwT7tjK%3Di6T908R8KgRU%3DVE3Roa8sqXdqYyzhGxyXA%40mail.gmail.com.

[Daniel Beck]

On Wed, May 19, 2021 at 8:08 AM 'Gavin Mogan' via Jenkins Developers <jenkin...@googlegroups.com> wrote:

I'm actually against updating the changelog. The changes to terminology were not done then, and by showing the old and the new, you show growth. I'm not a fan of rewriting history, even in git.

We're not "rewriting history" here. You wouldn't leave some wrong formatting around after migrating a file from Markdown to Asciidoc (or vice versa). You'd fix old typos. You'd adapt old links when the URL of the pages they point to change. And if we change the words we use to refer to something, that applies retroactively as well.

[Oleg Nenashev]

Hi all,

I am currently updating roadmap and the Jenkins website to reference the initiative and contributing.

To group everything and to coordinate contributions, I have created a Discourse topic here: https://community.jenkins.io/t/jenkins-terminology-cleanup-initiative-coordination/180 . I will be using it as a main source of contributing guidelines. Please feel free to contribute!

Best regards,

Oleg Nenashev

[Angélique Jard]

Hi everyone,

I am proposing a JEP to have all terms in a single place https://github.com/jenkinsci/jep/pull/368
My secret hope is to make it easy for new contributors or one day contributors (hacktahons, ...) to participate to the terminology update effort.

Feel free to join and/or to review this PR (and even more if you know other languages than English)

Angélique

[Fritz Elfert]

On 22.06.21 12:01, Oleg Nenashev wrote:
> Hi all,
>
> I am currently updating roadmap and the Jenkins website to reference the initiative and contributing.

> To group everything and to coordinate contributions, I have created a Discourse topic here: https://community.jenkins.io/t/jenkins-terminology-cleanup-initiative-coordination/180 <https://community.jenkins.io/t/jenkins-terminology-cleanup-initiative-coordination/180> . I will be using it as a main source of contributing guidelines. Please feel free to contribute!

What is still unclear to me (asked you in https://issues.jenkins.io/browse/JENKINS-62833) but no answer yet):
Does this also include java class names or only user-visible text/messages/doc?

Thanks
-Fritz

>
> Best regards,
> Oleg Nenashev
>
> On Wednesday, May 19, 2021 at 8:36:41 PM UTC+2 db...@cloudbees.com wrote:
>
> On Wed, May 19, 2021 at 8:08 AM 'Gavin Mogan' via Jenkins Developers <jenkin...@googlegroups.com> wrote:
>
> I'm actually against updating the changelog. The changes to terminology were not done then, and by showing the old and the new, you show growth. I'm not a fan of rewriting history, even in git.
>
>
> We're not "rewriting history" here. You wouldn't leave some wrong formatting around after migrating a file from Markdown to Asciidoc (or vice versa). You'd fix old typos. You'd adapt old links when the URL of the pages they point to change. And if we change the words we use to refer to something, that applies retroactively as well.
>

> --
> You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com <mailto:jenkinsci-de...@googlegroups.com>.
> To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/bdbaa768-fcf4-45d1-924d-52be07a39c88n%40googlegroups.com <https://groups.google.com/d/msgid/jenkinsci-dev/bdbaa768-fcf4-45d1-924d-52be07a39c88n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Gavin Mogan]

If a class name is serialized or used external to the plugin, its super hard to change without breaking compatibility. Generally the initial push is for using facing changes. Text strings, Help files. Docs. Etc

To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/27bb0f2a-5995-d6a2-1f39-11aa1d6670cf%40fritz-elfert.de.

[Oleg Nenashev]

+1 to what Gavin said. I cannot comment on a particular EPIC, but renaming classes is generally in the scope for the terminology cleanup initiative: https://community.jenkins.io/t/jenkins-terminology-cleanup-initiative-coordination/180#full-scope-5

"Being in scope" does not mean it will happen soon. All Jenkins initiatives depend on contributions, and the time many individual and company contributors are willing to invest. I totally agree with Gavin that user-facing items should be a priority. Then it should be developer facing things, where possible and feasible. If any contributor or end user has strong opinions about fixing a particular occurrence, they are welcome and encouraged to go ahead and submit pull requests. Lower priority does not mean the things should not be fixed now, everyone can work as they prefer.

You received this message because you are subscribed to a topic in the Google Groups "Jenkins Developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/jenkinsci-dev/x5vdlJDvntw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAG%3D_DusJ-2QmVF2xsuLRzoFi3GG5KsNtv%3DEz2rBUNCwNbMeb%3DQ%40mail.gmail.com.

[Angélique Jard]

Hello all :)

As a developer at CloudBees I am part of a team that is trying to participate in the terminology change effort and we had the same concern about the limits of changes (UI, logs, console, local variable, package name ??). So I can share our way of working so far =>

What we do first, is change only UI text and log/console text because it's fast with an immediate very visible change for end users and with very few backward compatibility issues (mainly test assertions to update).

We also changed the text in the comments, since the more terms are changed, the easier it is to see if there are some places with remaining deprecated words (so github search is faster).

I personally think that the ultimate goal would be to have the deprecated words removed everywhere including in code BUT this is complex to not break any backward compatibility.

I believe that anyone is free to go further, by being careful on backward compatibility because any piece of code can be user visible at some point, it can be a package name used on System property, a local field automatically exposed by Jenkins configuration as Code and or some future feature.

For code change we are looking one by one and see if it’s possible to have a backward compatible way, mainly by keeping along the old terminology and the new one. For example for Jenkins cli or Configuration as Code it’s quite easy to keep the deprecated terminology working as previously and just mark it as deprecated and in the same time adding the same code execution with the new naming convention. And remove the deprecated terminology, later, one day…. If I come up with ways that works fine (for cli or config as code or....) I will share them to the JEP I think.

I also believe in small steps  so I think it's better to split UI text changes and code change it make it more easy to review and test.

[Oleg Nenashev]

Thanks to Angelique for the summary and for creating a JEP based on the previous discussions and Google Docs. JEP-16 - Inclusive terminology guidelines and continuous updates has been accepted as a draft, and we can keep evolving it. Any feedback will be welcome!

The Inclusive naming initiative is now also listed on the Advocacy&Outreach page: https://www.jenkins.io/sigs/advocacy-and-outreach/#inclusive-naming

Best regards,

Oleg