Package naming convention for deprecated API migrations

[Radek Antoniuk]

I recently looked at Basil's PR migrating deprecated EE8 APIs to EE9:
https://github.com/jenkinsci/jira-plugin/pull/635.

Thank you for taking on this task—it’s much appreciated!

While reviewing the PR, I noticed a naming convention that I had hoped we’d moved past, hence my stupid comment in the PR. This led me to discover https://github.com/jenkinsci/stapler/pull/482, which had been reviewed by several contributors without raising concerns about the class naming. I decided it might be worth starting a discussion about this. 😊

Wouldn’t it enhance readability and maintainability to follow a consistent naming convention, such as the approach Jetty uses? Specifically, this could mean creating a dedicated package for such migrations. This way, we ensure clarity and maintainable organization for the future.

Ref: https://github.com/jenkinsci/jira-plugin/pull/613/files#diff-424c14a1c2b58da4b0795ac30fb529b8b0c021a59ed356f0a68297c0083d8f78R29

Regards,

Radek

[Mark Waite]

On Tuesday, January 28, 2025 at 1:59:49 PM UTC-7 Radek wrote:

I recently looked at Basil's PR migrating deprecated EE8 APIs to EE9:
https://github.com/jenkinsci/jira-plugin/pull/635.

Thank you for taking on this task—it’s much appreciated!

I agree with the thanks for all the work that Basil and others have done on Spring Security.  The migration has worked very well because of how hard Basil and others worked.

While reviewing the PR, I noticed a naming convention that I had hoped we’d moved past, hence my stupid comment in the PR. This led me to discover https://github.com/jenkinsci/stapler/pull/482, which had been reviewed by several contributors without raising concerns about the class naming. I decided it might be worth starting a discussion about this. 😊

I prefer the "2" suffix in the naming because I find it easier to read in-line.  I know that StaplerRequest is the old API and StaplerRequest2 is the new API.  The import statements are at the top of the file and I would rather not jump to the top of the file to decide which methods are being called.

 

Wouldn’t it enhance readability and maintainability to follow a consistent naming convention, such as the approach Jetty uses? Specifically, this could mean creating a dedicated package for such migrations. This way, we ensure clarity and maintainable organization for the future.

Consistency in naming convention is a reason whey I prefer the "2" suffix within Jenkins.  It was used by Kohsuke in some of the earliest API migrations.  It was used by Jesse Glick in other early API migrations.  The Jenkins migration from acegi to Spring Security (JEP-220 from 2020) used the "2" suffix.  The Spring Security 5 to Spring Security 6 and Java EE 8 to Jakarta EE 9 migration chose the same naming convention.

Mark Waite