Jenkins Terminology Cleanup initiative coordination

In 2016, the Jenkins community decided to change the non-inclusive terminology within the project. The “slave” term was deprecated and replaced by “agent” in Jenkins 2,0. In July 2020 we also adopted the “controller” term instead of “master”, and deprecated the “whitelist/blacklist” terms. There are many places where the old terminology still needs to be replaced.

We invite Jenkins contributors and users to join us and participate in cleaning up Jenkins documentation, Web and CLI interfaces, codebase, and all other occurrences. We want to replace the deprecated terminology by new terms: “controller”, “agent”, “allowlist”, “denylist”, and “main” for branch names. Feel free to ask any questions in the comments.

Contributing

We will appreciate any contributions! There are many relatively easy contributions anyone can make, with or without writing any code. Some of them require just a few minutes, and we more than welcome such contributions in our community.

Helping without writing code

  • Report issues. If you see something in the Jenkins UI or on our website, please do not hesitate to report it in respective component issue trackers (Jenkins Jira or GitHub Issues)
  • Review pull requests and provide feedback to other contributors. See the project on GitHub for some links.
  • Spread the word about the new Jenkins terms within your company or your community. Correct internal documentation and materials
  • Reach out to content creators and owners where the old terms are used, especially for the newly posted blogs, videos, and other materials. In your message reference the blog post and ask for updates.
    • Message example: Thanks for spreading the word and knowledge about Jenkins! As the community, we do not support using the deprecated terminology terminology, and we do not promote such content. It would be great if you could update your post. See this page for more details: https://community.jenkins.io/t/jenkins-terminology-cleanup-initiative-coordination/180

Newcomer-friendly issues

  • Fix newcomer-friendly issues in Jenkins Jira
  • Clean up plugin built-in documentation and documentation in Jenkins repositories
    • GitHub queries: “slave”, “slaves”, “Jenkins master”
    • If you work on these tasks, in the most of the cases you can just use GitHub web interface to edit files and submit pull requests.
    • Note that selecting a term is not always trivial for Jenkins controller sub-entities. For example, the “main” node on the Jenkibs controller is now called “Built-in node”, not the “Controller node”
      See this section for the chosen terms
  • Fix internationalization in your native language, including embedded docs. You can find the recommended terms for some of the languages here
  • Clean up Javadoc and code comments
  • Clean up documentation screenshots. It may require starting the instance and reproducing the layout on the screenshots

Other issue links

  • GitHub project in jenkinsci - GitHub issues and pull requests related to the terminology cleanup
  • JENKINS-42816 - EPIC for agent terminology cleanup in Jenkins Jira (Make sure to login to see the issues)
  • JENKINS-65398 - Terminology update for master, whitelist, blacklist

Full scope

Relatively trivial changes, no experience needed.

  • Jenkins Documentation (jenkins.io, plugin docs in GitHub, etc.) - Submit pull requests with fixes
  • Built-in plugin documentation and Web UI
  • Localization files - deprecated terminology equivalents in other languages
  • 3rd-party blogposts
  • Any code which is not a part of public AP or persistence modeI: private methods, local variables, comments, etc.

Non-trivial changes which may impact compatibility:

  • REST API endpoints - old endpoints should be retained for compatibility reasons
  • Symbols for JCasC/JobDSL/Pipeline - old symbols should be retained for compatibility reasons
  • Class Names and API where feasible. Retaining binary compatibility may require a massive effort
  • Renaming libraries and cleaning up used in Jenkins as upstream dependencies
  • Plugin Site and Update centers: Updating plugin labels and filters to avoid references in https://plugins.jenkins.io/. It may require introducing support for label synonyms
  • Plugin IDs - some plugins like SSH Build Agents Plugin still contain obsolete terms in plugin IDs. It is not possible to prevent that without a massive update of the Jenkins core and tooling
  • Changing the default branch in repositories from “master” to “main”. It might require updates of bot settings, GitHub Apps and Actions. See Changing the default branch - GitHub Docs
  • etc.

References

1 Like

In the same topic, I am on my way to propose a JEP to have the up to date terminology table reference there. Proposing a JEP to have terminology up to date status in a table. by aHenryJard · Pull Request #368 · jenkinsci/jep · GitHub if anyone want to be co-sponsor please tell me, I will be very happy to have some help to write it :slight_smile:

1 Like

Inclusive Naming is now officially listed on the Advocacy&Outreach SIG page: Advocacy and Outreach

Sharing here that during CloudBees terminology update on UI, Thierry did a tool to search for words in picture (OCR), as it open source and can be used by anyone I share it here too GitHub - twasyl/image-searcher
This has been highly usefull to find the screenshot that required to be updated. Thank you Thierry :wink: !!

1 Like