Hacktoberfest [JENKINS-69731] Update shared-libraries.adoc

content/doc/book/pipeline/shared-libraries.adoc

@@ -194,6 +194,64 @@ A link to the example repository used is also provided in the link:https://youtu
 
 video::eV7roTXrEqg[youtube,width=800,height=420]
 
+=== Statically loading evaluated versions of libraries
+
+As of currently unreleased version of the _Pipeline: Shared Groovy Libraries_ plugin,
+with features proposed in
+link:https://github.com/jenkinsci/pipeline-groovy-lib-plugin/pull/19[PR #19]
+(link:https://issues.jenkins.io/browse/JENKINS-69731[issue JENKINS-69731])
+there are new options for the `@Library` annotation with limited run-time evaluation
+of the version specified for the library. In order to use these features, you should
+explicitly allow them in library configuration (e.g. Global Jenkins configuration of
+your instance).
+
+While the markup for these features is intentionally similar to what you would write
+for Groovy code to simplify maintenance, keep in mind that the version tokens are
+handled by the plugin before it would load libraries and compile the pipeline script.
+
+One addressed use-case regards loading of "same version of library as the version of
+Pipeline script from SCM" by specifying literally +`${BRANCH_NAME}`+ as the library
+version in the pipeline script, e.g.:
+
+[source,groovy]
+----
+@Library('my-shared-library@${BRANCH_NAME}') _
+----
+
+The plugin tries several methods to determine the branch name to use, checks if
+the "version" is accepted by the SCM source of the library, and falls back to the default
+version if not.
+
+This was verified to work for:
+* MultiBranch Project pipelines both with "Modern SCM" and with "Single repository & branch"
+  (in case of the latter, the "name" you specify for the source is what matters for MBP more
+  than the actual SCM branch);
+* Pipelines backed by a single SCM source with a "Branch Specifier" like `*/main`;
+* "In-line" Pipelines not backed by an SCM (just fall back to default version).
+
+Another addressed use-case regards loading of some version of library specified by
+an environment variable value defined when the job starts (e.g. coming from Global
+Jenkins configuration or injected by a plugin):
+
+[source,groovy]
+----
+@Library('my-shared-library@${env.CUSTOM_VAR_NAME}') _
+----
+
+The plugin would try to get the `CUSTOM_VAR_NAME` from environment, and if it exists --
+check if such "version" is accepted by SCM source of the library, and fall back to
+default version if not.
+
+Note that pipeline sources before inclusion of `@Library` sources are parsed by the
+"built-in" build agent, so configuration of separate build agents should not matter
+in this context. This approach however allows to set up different Jenkins controllers
+to run the same pipeline scripts that would load different library sources based on
+the global-configuration value of `CUSTOM_VAR_NAME` on each Jenkins server. This can
+be useful to balance different implementations for different build farms and tooling
+(in-house proprietary for supported product vs. reference recipes for open source
+community), or different preferences to progress through dev/qa/staging/production
+separate environments.
+
 === Loading libraries dynamically
 
 As of version 2.7 of the _Pipeline: Shared Groovy Libraries_ plugin,