Add Jenkins template variables for slash normalization handling.

Review Request #13861 — Created May 15, 2024 and submitted

Information

rbintegrations
release-4.x

Reviewers

Our Jenkins implementation normalizes slashes in job names to
underscores, in order to avoid issues with certain versions of Jenkins.
It turns out that this really only applied to a specific range of
versions, and that both prior and latter versions need to retain the
slash. This behavior has been a blocker on supporting newer versions of
Jenkins.

Rather than try to determine what's best for the install, we now give
users more control over the process by way of new variable names.

The old {branch} and {repository} names (which normalized slashes in
some versions and didn't in others) are now deprecated and no longer
documented in the field's help text.

Instead, we now have {branch_name} and {repository_name}, which do
not normalize, and {noslash_branch_name} and
{noslash_repository_name}, which do normalize.

Existing configurations will continue to work as before, for the most
part. While the legacy variable names are still there, we no longer
normalize the entire job name, so if a job name had slashes explicitly
provided and expected them to be changed to underscores, they'll need to
update those to use underscores instead.

Because of the change to normalization rules across the provided job
name, this is considered a potentially breaking change, for those that
needed slashes normalized before, and will need to be documented as
such.

Unit tests pass.

Summary ID
Add Jenkins template variables for slash normalization handling.
Our Jenkins implementation normalizes slashes in job names to underscores, in order to avoid issues with certain versions of Jenkins. It turns out that this really only applied to a specific range of versions, and that both prior and latter versions need to retain the slash. This behavior has been a blocker on supporting newer versions of Jenkins. Rather than try to determine what's best for the install, we now give users more control over the process by way of new variable names. The old `{branch}` and `{repository}` names (which normalized slashes in some versions and didn't in others) are now deprecated and no longer documented in the field's help text. Instead, we now have `{branch_name}` and `{repository_name}`, which do not normalize, and `{noslash_branch_name}` and `{noslash_repository_name}`, which do normalize. Existing configurations will continue to work as before, for the most part. While the legacy variable names are still there, we no longer normalize the entire job name, so if a job name had slashes explicitly provided and expected them to be changed to underscores, they'll need to update those to use underscores instead. Because of the change to normalization rules across the provided job name, this is considered a potentially breaking change, for those that needed slashes normalized before, and will need to be documented as such.
2fb0f124222b2e379668e679227da747b75dd711
Description From Last Updated

We could add some extra context here, saying something like: "If you're using an older version of Jenkins you may …

maubinmaubin
maubin
  1. Just a reminder that we'll need to update the Jenkins CI Integration docs as well.

    1. Yep! Good reminder. Got that in progress in the Review Board tree now.

  2. rbintegrations/jenkinsci/forms.py (Diff revision 1)
     
     
     
     
     
     
     
     
     
    Show all issues

    We could add some extra context here, saying something like: "If you're using an older version of Jenkins you may need to use the {noslash_} variables." or ideally instead of saying "an older version" you could give the verison range.

    1. Good idea. I need to figure out precisely what that range really is.

    2. Okay, so the tickets surrounding this as really convoluted and unclear. I'm not 100% sure if the solution here will, in practice, solve the problems, as there's a lot of discussion around several different aspects surrounding the / issue.

      I'm also not 100% sure on the version ranges in question. The version numbers referenced in the ticket don't have corresponding ChangeLog entries. And no ChangeLog entries (including old archived entries) talk about the allowed characters in the job name.

      Based on comments from a customer, and based on the age of the tickets, I think that in most cases the {branch_name} and {repository_name} will be correct. But I don't know. I hesitate at this point to put any version ranges in there without having a much better understanding of this.

    3. I see. Then maybe stick with "If you're using an older version of Jenkins ...".

  3. 
      
chipx86
misery
  1. 
      
  2. Thanks for the info. I'm fine with the extra variables.
    I can look into our Jenkins if it is still necessary. But that will take some time.

  3. 
      
david
  1. Ship It!
  2. 
      
maubin
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-4.x (0c2c74a)