You've extracted common pipeline logic into a Jenkins shared library used by 40+ Jenkinsfiles. How do you version it so you can improve the library without breaking every pipeline that depends on it?

Pin each Jenkinsfile to a specific shared library version explicitly (@Library('my-lib@v2.3.0')) rather than defaulting to the library's main/latest branch, so a change to the library only affects a pipeline when that pipeline's owner deliberately bumps its pin — treat the shared library like any other versioned dependency, not like a shared mutable resource every pipeline automatically inherits changes from.

The failure mode with an unversioned or loosely-versioned shared library is the same class of problem as a floating dependency version anywhere else: a change made for one team's use case can silently break another team's pipeline the next time it runs, with no warning and no reviewable diff on the consuming side — exactly the kind of blast radius you want to avoid when 40+ pipelines all depend on the same code.

• A change to the shared library must not automatically affect every consuming pipeline the next time it runs.
• Pipeline owners must be able to adopt a new library version deliberately, on their own schedule.
• The library itself still needs a path to actually ship improvements and fixes, without requiring 40+ manual coordination conversations for every change.

Explicit version pinning per Jenkinsfile: each Jenkinsfile references the shared library at a specific tagged version (@Library('my-lib@v2.3.0')), not a branch name like main — this is the core mechanism that gives every pipeline control over when it takes a library update, turning an implicit, invisible dependency into an explicit, reviewable one (the version bump shows up as a diff in that pipeline's own Jenkinsfile).

Semantic versioning and a real changelog for the library itself: tagging library releases with semantic versioning (breaking changes bump the major version) and maintaining a changelog gives consuming teams enough information to judge whether adopting a new version is safe or requires changes on their end, rather than having to read the library's full diff themselves.

A deprecation window for breaking changes, not silent removal: when the library needs to change something in a backward-incompatible way, keeping the old behavior available (perhaps behind the old major version tag) for a defined window gives teams time to migrate on their own schedule, rather than forcing an immediate break.

Automated notification, not automated adoption: notifying pipeline owners when a new library version is available (a bot comment, a dashboard, a Slack notification) keeps teams aware of updates without forcing automatic adoption — the notification creates visibility; the explicit version pin still keeps adoption a deliberate, owned decision.

Explicit pinning means library improvements (including security fixes) don't automatically reach every pipeline — some teams may lag on old, potentially vulnerable versions if there's no process encouraging them to update. This needs a lightweight but real mechanism (periodic reminders, or treating badly outdated pins as a tracked item) to avoid the opposite failure mode: pins that are set once and never revisited, defeating some of the value of having a shared, improvable library at all.

• Pin each Jenkinsfile to an explicit shared library version, not a branch — this is what prevents a library change from silently breaking every consuming pipeline.
• Semantic versioning and a real changelog let consuming teams judge whether an update is safe without reading the full library diff.
• Give breaking changes a deprecation window rather than removing old behavior immediately, so teams can migrate on their own schedule.
• Balance explicit pinning against staleness risk — notify teams of new versions so pins get revisited periodically, rather than being set once and forgotten.

• Jenkins Docs: Shared Libraries