Add Javadoc for the categories

[daniel-beck]

Followup to #4546: I expected a lot of feedback on what the categories should be, so did hold back on defining them in more detail. I ended up getting absolutely no feedback on the category definitions before the change got integrated, so this is the followup PR with definitions.

We might still be able to redefine categories here, so if you really don't like what we have, let me know (and why!).

Proposed changelog entries

• Add Javadoc for management link category definitions

Proposed upgrade guidelines

N/A

Submitter checklist

• [n/a] JIRA issue is well described
• Changelog entries and upgrade guidelines are appropriate for the audience affected by the change (users or developer, depending on the change). Examples
  • Fill-in the Proposed changelog entries section only if there are breaking changes or other changes which may require extra steps from users during the upgrade
• [n/a] Appropriate autotests or explanation to why this change has no tests
• [n/a] For dependency updates: links to external changelogs and, if possible, full diffs

Desired reviewers

@mention

Maintainer checklist

Before the changes are marked as ready-for-merge:

• There are at least 2 approvals for the pull request and no outstanding requests for change
• Conversations in the pull request are over OR it is explicit that a reviewer does not block the change
• Changelog entries in the PR title and/or Proposed changelog entries are correct
• Proper changelog labels are set so that the changelog can be generated automatically
• If the change needs additional upgrade steps from users, upgrade-guide-needed label is set and there is a Proposed upgrade guidelines section in the PR title. (example)
• If it would make sense to backport the change to LTS, a JIRA issue should exist and be labeled as lts-candidate

[oleg-nenashev]

I plan to merge it tomorrow if no negative feedback

[daniel-beck]

Would prefer we gave this some more time to allow for feedback, doesn't make a difference if merged tomorrow or on Saturday. This is less about the Javadoc than its content.

[MarkEWaite]

Here is my attempt to classify the Uncategorized in my Jenkins installation. How do my categorizations compare with how you would categorize the same items?

• CONFIGURATION - "System Configuration"
  • Configuration Slicing
  • Configuration as Code
  • Managed files
  • Label implications
• SECURITY - "Security"
  • Configure Credentials
  • In-process Script Approval
  • Support Bundle Anonymization
• STATUS - "Status Information"
  • DevOptics
• TROUBLESHOOTING - "Troubleshooting"
  • Manage Jenkins Health Advisor by CloudBees
• TOOLS - "Tools and Actions" (should the enum be TOOLS_AND_ACTIONS to persuade people to not think about tool installers?)
• MISC - "Miscellaneous"
• UNCATEGORIZED - "Uncategorized"

If those seem mostly reasonable to you, then I think that indicates I've understood the explanation in the javadoc. If I classified something incorrectly, that should not block the merge of this pull request.

I also checked all the different sizes offered by the 'Resizer' app on my Windows machine. The layout looks really good in all of them.

[daniel-beck]

@MarkEWaite Thanks, that's a great idea for us to get consensus or identify unclear categories.

Configuration Slicing

https://plugins.jenkins.io/configurationslicing/

I would call this a Tool. It allows admins to quickly see and change a single aspect of configuration across many jobs.

Configuration as Code

This would fit into multiple categories, e.g. the Reload feature on its own would be a Tool. Still, General configuration fits.

Managed files

General. Agree.

Label implications

General works. Would also not reject Misc.

Configure Credentials

Security. Agree.

In-process Script Approval

Security. Agree.

DevOptics

I would call DevOptics itself (at least what I've seen) "Status", but it's unclear to me what the item does once I've set up DevOptics. Might also be Misc, General.

Manage Jenkins Health Advisor by CloudBees

Troubleshooting based on what I see there without enabling it. Agree.

Support Bundle Anonymization

I am unsure what this item does. The UI isn't exactly helpful if you click on it, perhaps because my test instance has never created a support bundle. Based on the name and what I heard about the feature, it could make sense to put it here, or Misc.

It would be more straightforward if this was part of the "Support" action and that was placed here, in that case, Troubleshooting would be obvious based on its primary use case, Status wouldn't be wrong either IMO.

[timja]

Previous build passed:
https://ci.jenkins.io/blue/organizations/jenkins/Core%2Fjenkins/detail/PR-4578/5/pipeline