jenkins.io
jenkins.io copied to clipboard
jenkins-infra
Remove references to “instance”
Describe your use-case which is not covered by existing documentation.
This repository has hundreds of references to a Jenkins “instance,” a particularly irritating term that has neither a clear meaning nor a definition in the glossary. (The only clear concept of “instance” in the Jenkins ecosystem is Instance Identity, which is an internal implementation detail that is likely out of scope for most documentation.) The term should likely be replaced with “controller” in most cases.
Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.
No response
Thank you, Basil.
I must admit, I frequently use it in my blog posts.
What term would you use to refer to the combination of a controller, one or more agents, and/or clouds?
Related PR for plugin site https://github.com/jenkins-infra/plugin-site/pull/1743 (just merged)
“Deployment” might be a good term to use in that situation—while a bit vague (for example, a Jenkins deployment could include multiple controllers), it is still more specific than “environment” or “instance,” which could be referring to just about anything, even an instance of a Java object (of which there are thousands within a controller JVM process). Most of the usages I found really did mean “controller” (e.g., logging into an ~instance~ controller), but in rare cases where precision is required and “deployment” is too vague then perhaps one could use the more laborious phrase “controller and agents.”
Hi @basil, thank you very much for raising this issue! I was compiling the various usage throughout jenkins.io and can confirm there's a few hundred uses throughout. It appears that about 1/3 of the usage occurs throughout the documentation, while the bulk are found in blog posts and security advisories. There are a couple of uses in other areas that are not necessarily used in the site (old changelogs) but they are the exception rather than the norm. The blog posts would be left alone for historical purposes and security advisories would typically be left as is since Security owns the advisories. I'm happy to start tackling the documentation usage though so that we can be more accurate.
Thank you for providing the suggestions here to use either "controller", "jenkins deployment" or "controllers and agents", I'll be sure to examine the context and make sure they are applied accordingly.
@kmartens27 careful of control words in your PR descriptions https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue
Ideally GitHub would require it to be on a new line on its own but it picks it up in a sentence 😢
Noting per https://github.com/jenkins-infra/jenkins.io/pull/7473#issuecomment-2329355704 that the linked PRs only change occurrences of "Jenkins instance" while leaving "instance" alone.
I was discussing this with @MarkEWaite earlier, but instead of changing the usage of "instance", would it make more sense and provide the definition and clarity that @basil is looking for if we defined instance in the Jenkins glossary? As @daniel-beck had pointed out on the security PR, instance is used throughout several areas and other coding/development documentation so there is precedent for it to exist and be used.
There are plenty of sites/products/projects that have a definition for instance, and we could follow the pattern by doing the same for Jenkins.
How would you define it, and what would be the difference between it and "controller"?
IMO this issue description makes a good argument for a change: Usually it means the same thing as "controller" (and when it doesn't, "instance" seems off, with something like "deployment" or "system" probably better).
Additional update for documentation: https://github.com/jenkins-infra/jenkins.io/pull/7619.
Closing as the remaining usage of instance is more general and not directly translating to "jenkins controller" or "jenkins controller and agents". If not this, it is referring to another program/platform and using an instance of them.