Help request: Naming things is hard (JENKINS-43426)

[Stephen Connolly]

Famously, in computer science there are only two hard problems:

1. Cache invalidation

2. Naming things

3. Off-by-one counting bugs

In the GitHub Branch Source and Bitbucket Branch Source plugins I am currently trying to refactor the UI with a number of goals:

1. Make it easier for users to understand what the different configuration options do

2. Make it easier for plugin developers to enhance the functionality and provide more complex variants.

3. Add some configuration aspects that are currently not possible.

In terms of the code structure for this refactoring I have a good idea as to the shape of the solution that will work *within the constraints of the Jenkins Classic UI paradimes*.

Here is an animated GIF showing the approximate shape of the solution.

What I now need to solve, while also refactoring this UI to share commonality between Bitbucket and GitHub (as well as allowing e.g. Gogs and GitLab to leverage this same commonality) is the naming of things. This is where you can come in.

I need good names for things.

• There are a pile of things that will be able to be attached to a branch source. In the code I am calling these Traits. That name does not make good sense for users. In the above animation I call them Behaviours.
  
  The list of ones will also include a subset of the Git SCM "Additional Behaviours" such as clean before/after checkout, etc
  
  Can you suggest a better UI name for traits than Behaviors?
  
  
• Currently the GitHub Branch Source has two check-boxes to control whether it discovers branches on the repository. If you check one of these two boxes then either you will get all the branches that are not also a PR or all the branches that are also a PR (this second one seems nuts but backwards compatibility). If you check both of the boxes you get all the branches.
  
  I have replaced these two checkboxes with a trait. The trait has a drop down configuration that lets you select the three combinations of which branches to build. The 4th combination (corresponding to not checking either of the checkboxes in the current UI) is to just remove the trait.
  
  Can you suggest a better UI name for this trait than "Discover branches"?
  Does "Discover branches" scream out what it does?
  Can you suggest a better UI name for the "Strategy" field in "Discover branches"?
  Can you suggest better names for any of the 3 strategy options?
  
  
• Currently the GitHub Branch Source has two check boxes to control both whether it discovers pull requests originating from the repository itself and how to build those pull requests.
  
  I have replaced these two checkboxes with a trait. The trait has a drop-down configuration. Selecting either the 1st or the 2nd of these options will build either the merge or the head commit and will call the branches PR-xxx. Selecting the 3rd of these options will build two branches for every PR one called PR-xxx-merge and one called PR-xxx-head.
  
  Can you suggest a better UI name for this trait than "Discover pull requests from origin"?
  Does "Discover pull requests from origin" scream out what it does?
  Can you suggest a better UI name for the "Strategy" field in "Discover pull requests from origin"?
  Can you suggest better names for any of the 3 strategy options?
  
  
• Currently the GitHub Branch Source has two check boxes to control both whether it discovers pull requests originating from forks of the repository and how to build those pull requests
  
  I have replaced these two checkboxes with a trait.
  
  The trait has a drop-down configuration for selecting what to build. Selecting either the 1st or the 2nd of these options will build either the merge or the head commit and will call the branches PR-xxx. Selecting the 3rd of these options will build two branches for every PR one called PR-xxx-merge and one called PR-xxx-head.
  
  The trait also has a drop down configuration for selecting how to "trust" pull requests from forks. New feature. Currently only pull requests from collaborators are trusted. This new feature will enable control on how a pull request gets trusted. Along with additional features - such as being able to block automatic builds of non-trusted pull requests - this should enable a lot more control (e.g. an extension plugin could only trust pull requests where a collaborator had added a comment with a magic string or assigned a label)
  
  Can you suggest a better UI name for this trait than "Discover pull requests from forks"?
  Does "Discover pull requests from forks" scream out what it does?
  Can you suggest a better UI name for the "Strategy" field in "Discover pull requests from forks"?
  Can you suggest better names for any of the 3 strategy options?
  Can you suggest a better UI name for the "Trust" field in "Discover pull requests from forks"?
  Can you suggest better names for any of the current base default 3 strategy options: "Collaborators", "None" and "Everyone"?
  
  
• Currently, hidden in the advanced box there is an Includes/Excludes option. There are a lot of requests for different syntaxes of specifying includes / excludes. Due to backwards compatibility we cannot change the syntax, so my solution is to allow plugins to extend and add traits for the different syntaxes. 
  
  To retain backwards compatibility of existing configurations, we need to provide one that uses the current wildcard (without globs) matching.
  
  Can you suggest a better UI name for this trait than "Filter by name (with wildcards)"?
  Does "Filter by name (with wildcards)" scream out what it does?
  
  
• Currently there is some confusion about the difference between Scan credentials and Checkout credentials. After some analysis, the conclusion I reached is that Checkout credentials are used when you want to checkout over SSH. As such I think it is simpler for users to just present one set of credentials and when a user wants to force the checkout over SSH let them add a trait to switch the checkout to SSH.
  
  Can you suggest a better UI name for this trait than "Checkout over SSH"?
  Does "Checkout over SSH" scream out what it does?
  
  

Thanks in advance for your assistance. Any suggestions are welcome, even if we do not use them as is, they may provide inspiration 

-Stephen

[Martin d'Anjou]

Disclaimer: I do not use those plugins.

Can you suggest a better UI name for this trait than "Discover branches"?

No.

Does "Discover branches" scream out what it does?

Yes.
 

Can you suggest a better UI name for the "Strategy" field in "Discover branches"?

No.

• Can you suggest better names for any of the 3 strategy options?

Anything that contains something resembling a double negative confuses me, e.g. "only that are not also", so if I understand correctly the types of branches that may exist, this is my suggestion:
* Only PR branches
* Only non-PR branches
* All branches

• Currently the GitHub Branch Source has two check boxes to control both whether it discovers pull requests originating from the repository itself and how to build those pull requests.
  
  I have replaced these two checkboxes with a trait. The trait has a drop-down configuration. Selecting either the 1st or the 2nd of these options will build either the merge or the head commit and will call the branches PR-xxx. Selecting the 3rd of these options will build two branches for every PR one called PR-xxx-merge and one called PR-xxx-head.
  
  Can you suggest a better UI name for this trait than "Discover pull requests from origin"?
  Does "Discover pull requests from origin" scream out what it does?
  Can you suggest a better UI name for the "Strategy" field in "Discover pull requests from origin"?
  Can you suggest better names for any of the 3 strategy options?
  
  

Ditto and:
In BitBucket Server, pull-requests exist on the upstream, not on the origin. But what does "origin" refer to here?
In terms of better names for the strategies:
* Checkout target branch and merge pull-request to it
* Checkout pull-request
* Do both (in separate builds) - (this is my understanding and I could be wrong)
 

• Can you suggest a better UI name for this trait than "Discover pull requests from forks"?
  Does "Discover pull requests from forks" scream out what it does?
  Can you suggest a better UI name for the "Strategy" field in "Discover pull requests from forks"?
  Can you suggest better names for any of the 3 strategy options?

Ditto.

But now I am confused. Pull-requests in BitBucket Server have 4 coordinates: source repo, source branch, target repo and target branch. This results in the target branch being created on the target repo. And the target repo is the only place where the pull-request can be discovered, as far I as I know. So I am not sure what "discovering pull-requests on forks" means vs. "discover pull requests from origin".
 
To me, a Jenkins Job should have a single purpose, and to me a single purpose is to merge a pull request to a single possible destination. If the Jenkins Job is able to merge to different destinations, then it's not the same Job because it does not serve the same purpose.

• Can you suggest a better UI name for the "Trust" field in "Discover pull requests from forks"?
  Can you suggest better names for any of the current base default 3 strategy options: "Collaborators", "None" and "Everyone"?

Who is the list of collaborators and how does someone get there?
None -> Nobody?
 

• Currently, hidden in the advanced box there is an Includes/Excludes option. There are a lot of requests for different syntaxes of specifying includes / excludes. Due to backwards compatibility we cannot change the syntax, so my solution is to allow plugins to extend and add traits for the different syntaxes. 
  
  To retain backwards compatibility of existing configurations, we need to provide one that uses the current wildcard (without globs) matching.
  
  Can you suggest a better UI name for this trait than "Filter by name (with wildcards)"?

What is being filtered by name? The name of the pull-request branch? The name of the pull-request? 

Hope this helps,
Martin

[Stephen Connolly]

Not just separate builds, separate jobs. One job for PR-head and one job for PR-merge

 

• Can you suggest a better UI name for this trait than "Discover pull requests from forks"?
  Does "Discover pull requests from forks" scream out what it does?
  Can you suggest a better UI name for the "Strategy" field in "Discover pull requests from forks"?
  Can you suggest better names for any of the 3 strategy options?

Ditto.

But now I am confused. Pull-requests in BitBucket Server have 4 coordinates: source repo, source branch, target repo and target branch. This results in the target branch being created on the target repo. And the target repo is the only place where the pull-request can be discovered, as far I as I know. So I am not sure what "discovering pull-requests on forks" means vs. "discover pull requests from origin".

So this is discovering PRs where the source repo != target repo

 
To me, a Jenkins Job should have a single purpose, and to me a single purpose is to merge a pull request to a single possible destination. If the Jenkins Job is able to merge to different destinations, then it's not the same Job because it does not serve the same purpose.

Each "head" gets their own Job

• Can you suggest a better UI name for the "Trust" field in "Discover pull requests from forks"?
  Can you suggest better names for any of the current base default 3 strategy options: "Collaborators", "None" and "Everyone"?

Who is the list of collaborators and how does someone get there?
None -> Nobody?
 

• Currently, hidden in the advanced box there is an Includes/Excludes option. There are a lot of requests for different syntaxes of specifying includes / excludes. Due to backwards compatibility we cannot change the syntax, so my solution is to allow plugins to extend and add traits for the different syntaxes. 
  
  To retain backwards compatibility of existing configurations, we need to provide one that uses the current wildcard (without globs) matching.
  
  Can you suggest a better UI name for this trait than "Filter by name (with wildcards)"?

What is being filtered by name? The name of the pull-request branch? The name of the pull-request? 

Hope this helps,
Martin

--
You received this message because you are subscribed to the Google Groups "Jenkins Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-use...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/a6551467-5575-44f1-a0be-4ce644422668%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Sent from my phone