Assigning Labels to Plugins

[Mark Waite]

Managing the labels on plugins has become much simpler with the transition to GitHub topics for label management.  Thanks to Gavin Mogan for the great improvements to the plugins site!

When one of the whitelisted labels is added as a topic on a plugin repository, that label will be associated with the plugin on the plugins site.

I think there are some general principles to let labels be the best help for users.  I propose:

• Label for users - It is more important that labels benefit plugin users than plugin developers
• Label from the whitelist - Searches by plugin users have better results when labels are consistent
• Prefer widely applicable labels - Labels with very few plugins using the label are less likely to help users than labels with many plugins
• Skip labels provided by parents - When a plugin depends on another plugin, the dependency will be installed automatically.  A label is not required on the dependency if the consuming plugin has the label

I think we might also benefit from guidelines for label additions to the whitelist.  For example, possible guidelines might include:

• Labels should be relevant to at least 5 plugins before they are accepted in the whitelist.  Pull requests to add to the whitelist should include the list of plugins which should receive the proposed label
• Labels should help users find plugins especially when the plugin name does not immediately associate with the label

Here are some samples to test those principles and guidelines:

1. Which plugins should be labeled 'github'?
   Any plugin that might help a GitHub user get more value from GitHub.  For example, "Basic Branch Build Strategies" is not specific to GitHub but would provide value to a GitHub user.  It should include the "github" label
   
2. Which plugins should not be labeled 'github'?
   The git plugin and the git client plugin will  both be installed automatically as dependencies of most of the plugins labeled 'github'.  Don't label them 'github' because that label won't help the user get the most value from GitHub.
3. Which plugins should be labeled 'sonar'?
   Any plugin that might help a Sonar user get more value from Sonar.  For example, "Warnings NG" is not specific to Sonar but seems like a good candidate for a "sonar" label because it might help Sonar users
4. Which plugins should be labeled "gitea"?
   Any plugin that might help a Gitea user get more value from Gitea.  For example, "Basic Branch Build Strategies" is not specific to Gitea but would provide value to a Gitea user.  It should include the "gitea" label

Comments, questions, concerns?

Mark Waite

[Oleg Nenashev]

I suggest to discuss it at the next Docs SIG meeting (Mar 13). Sorry that I did not follow-up timely.

Which plugins should be labeled 'github'?
Any plugin that might help a GitHub user get more value from GitHub.  For example, "Basic Branch Build Strategies" is not specific to GitHub but would provide value to a GitHub user.  It should include the "github" label

This is a nice principle, but it is IMHO too wide for interpretation. E.g. Pipeline and Blue Ocean plugins can help a GitHub user to get more value from GitHub integrations. Should we tag around 60 Pipeline/BlueOcean plugins as 'github'? Unlikely, because it will undermine the value of the label by offering a massive number of barely related plugins. There are generic tags like "pipeline" for them. "Basic Branch Build Strategies" is definitely useful for GitHub, as well as many other generic SCM plugins. IMHO we need to provide a clear patch for users to discover such generic plugins, but not through direct labeling (e.g. "Users of this plugin usually install these plugins..." like in online shops). There are also generic "scm" labels which could help to group such added-value plugins

Which plugins should not be labeled 'github'?
The git plugin and the git client plugin will  both be installed automatically as dependencies of most of the plugins labeled 'github'.  Don't label them 'github' because that label won't help the user get the most value from GitHub.

IMHO this principle contradicts the first one.

1. Which plugins should be labeled 'sonar'?
   Any plugin that might help a Sonar user get more value from Sonar.  For example, "Warnings NG" is not specific to Sonar but seems like a good candidate for a "sonar" label because it might help Sonar users
2. Which plugins should be labeled "gitea"?
   Any plugin that might help a Gitea user get more value from Gitea.  For example, "Basic Branch Build Strategies" is not specific to Gitea but would provide value to a Gitea user.  It should include the "gitea" label

TBH both examples rather convince me that we should reconsider the criteria suggested in (1). It would be great to get feedback from plugin maintainers whether they would label them with such "downsteram consumer plugin" label, but I am not sure about it. 

BR, Oleg

[James Nord]

> Skip labels provided by parents - When a plugin depends on another plugin, the dependency will be installed automatically. A label is not required on the dependency if the consuming plugin has the label

but if the parent can be used without the child (extension) then how does that parent get found in isolation. The only case of not labelling the parent is when it provides no user feature in my opinion (eg it's a pure api plugin)

[Mark Waite]

On Tuesday, March 10, 2020 at 2:23:10 AM UTC-6, Oleg Nenashev wrote:

I suggest to discuss it at the next Docs SIG meeting (Mar 13). Sorry that I did not follow-up timely.

I've added it to the agenda for the next Docs SIG meeting, March 27, 2020.  We've shifted Docs SIG meetings to monthly on the fourth Friday of each month.

 

Which plugins should be labeled 'github'?
Any plugin that might help a GitHub user get more value from GitHub.  For example, "Basic Branch Build Strategies" is not specific to GitHub but would provide value to a GitHub user.  It should include the "github" label

This is a nice principle, but it is IMHO too wide for interpretation. E.g. Pipeline and Blue Ocean plugins can help a GitHub user to get more value from GitHub integrations. Should we tag around 60 Pipeline/BlueOcean plugins as 'github'? Unlikely, because it will undermine the value of the label by offering a massive number of barely related plugins. There are generic tags like "pipeline" for them. "Basic Branch Build Strategies" is definitely useful for GitHub, as well as many other generic SCM plugins. IMHO we need to provide a clear patch for users to discover such generic plugins, but not through direct labeling (e.g. "Users of this plugin usually install these plugins..." like in online shops). There are also generic "scm" labels which could help to group such added-value plugins

That's a very good point.  I assumed we would address that class of problem by assigning the 'github' label to one plugin, 'blue ocean', then rely on the Jenkins dependency resolution process to load all the necessary dependencies for that plugin.  Same principle would apply to Bitbucket.  That was what I was trying to express with "Skip labels provided by parents".  In that sense, the Blue Ocean aggregator is the parent and would be labeled github, bitbucket, git, and more.  The plugins automatically installed as dependencies of the blue ocean plugin would not need any of those labels.

I think you're correct that the user value of a label is reduced significantly if the list of plugins with that label is cluttered.  I think clutter could be reduced significantly by choosing to label aggregators without labeling the things which are dependencies of the aggregators.

 

Which plugins should not be labeled 'github'?
The git plugin and the git client plugin will  both be installed automatically as dependencies of most of the plugins labeled 'github'.  Don't label them 'github' because that label won't help the user get the most value from GitHub.

IMHO this principle contradicts the first one.

Yes, I knew there was a contradiction in those two principles.  I wanted to encourage the application of all the principles, with the "Skip labels provided by parents" as a principle of exclusion.  The git client plugin would be included by the first 3 principles but then would be excluded by the "Skip labels provided by parents" principle.

 

1. Which plugins should be labeled 'sonar'?
   Any plugin that might help a Sonar user get more value from Sonar.  For example, "Warnings NG" is not specific to Sonar but seems like a good candidate for a "sonar" label because it might help Sonar users
2. Which plugins should be labeled "gitea"?
   Any plugin that might help a Gitea user get more value from Gitea.  For example, "Basic Branch Build Strategies" is not specific to Gitea but would provide value to a Gitea user.  It should include the "gitea" label

TBH both examples rather convince me that we should reconsider the criteria suggested in (1). It would be great to get feedback from plugin maintainers whether they would label them with such "downsteram consumer plugin" label, but I am not sure about it. 

Agreed that I would love to have feedback from plugin maintainers whether they would label with "downstream consumer plugin" labels.  Would the maintainer of "Basic Branch Build Strategies" be willing to add labels for github, bitbucket, gitea, and gitlab?  

[Mark Waite]

On Tuesday, March 10, 2020 at 3:21:34 AM UTC-6, James Nord wrote:

> Skip labels provided by parents - When a plugin depends on another plugin, the dependency will be installed automatically.  A label is not required on the dependency if the consuming plugin has the label

but if the parent can be used without the child (extension) then how does that parent get found in isolation. The only case of not labelling the parent is when it provides no user feature in my opinion (eg it's a pure api plugin)

What I was envisioning was:

Bitbucket Branch Source plugin depends on git plugin.  Bitbucket Branch Source plugin would be labeled 'bitbucket'.  Git plugin would not be labeled 'bitbucket' because it will be installed automatically when Bitbucket Branch Source is installed.

Git plugin depends on git client plugin.  Git plugin would be labeled 'git'.  Git client plugin would not be labeled 'git' because it will be installed automatically when Git plugin is installed.  Git client plugin is an example of a pure API plugin and would have very few labels.

I think the Bitbucket Branch Source -> Git plugin case is an example of your concern for locating a plugin in isolation.  In that case, a search for the 'bitbucket' label will not show the git plugin.  I was assuming that a Bitbucket user will prefer to install one of the higher level integrations (Bitbucket plugin, Bitbucket Branch Source plugin, Bitbucket Pullrequest BUilder, Bitbucket Server Notifier, etc.) and will receive the git plugin and the git client plugin as dependencies because they chose one or more of the higher level integration plugins.

Did I understand your concern?

[Mark Waite]

We discussed today in the Jenkins Documentation Special Interest Group and came to the agreement that I will submit a pull request to the Jenkins plugin developer documentation that:

• Encourages developers to apply GitHub topics to plugins they maintain
• Note that topics which match the whitelist will be displayed on plugins.jenkins.io
• Suggests that topics should be assigned to a plugin when the plugin relationship to the label is well above average
• Invites pull requests to recommend additions to the label whitelist
• Encourage developers to ask avoid applying labels which are so broad that they lose value because of overuse.  For example, the labels "Jenkins" and "plugin" are not helpful because they apply almost everywhere

Pull request should arrive later today

[Mark Waite]

https://github.com/jenkins-infra/jenkins.io/pull/3012 is the pull request that tires to describe labeling.

--
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/a4bee5a1-5fcc-4fbe-a8e6-bf8e27257328%40googlegroups.com.