Clarify that plugin depends on release cycle of client5

Author: strangelookingnerd

README.adoc

@@ -22,8 +22,11 @@ It allows managing library updates independently of plugins.
 
 Replace the dependency to `org.apache.httpcomponents.client5:httpclient5` with the dependency to `apache-httpcomponents-client-5-api`.
 
+Avoid version conflicts by using the https://github.com/jenkinsci/bom[Jenkins Plugin BOM] rather than depending on a specific version.
+
 *Before:*
 
+[source,xml]
 ----
 <dependencies>
   ...
@@ -38,13 +41,13 @@ Replace the dependency to `org.apache.httpcomponents.client5:httpclient5` with t
 
 *After:*
 
+[source,xml]
 ----
 <dependencies>
   ...
   <dependency>
     <groupId>org.jenkins-ci.plugins</groupId>
     <artifactId>apache-httpcomponents-client-5-api</artifactId>
-    <version>5.2.1-1.0</version>
   </dependency>
   ...
 </dependencies>
@@ -54,8 +57,11 @@ Replace the dependency to `org.apache.httpcomponents.client5:httpclient5` with t
 
 Add the dependency to `apache-httpcomponents-client-5-api` *before* any of dependencies to those libraries to force maven to use `httpclient5` declared by `apache-httpcomponents-client-5-api`.
 
+Avoid version conflicts by using the https://github.com/jenkinsci/bom[Jenkins Plugin BOM] rather than depending on a specific version.
+
 *Before:*
 
+[source,xml]
 ----
 <dependencies>
   ...
@@ -73,13 +79,13 @@ Add the dependency to `apache-httpcomponents-client-5-api` *before* any of depen
 
 *After:*
 
+[source,xml]
 ----
 <dependencies>
   ...
   <dependency>
     <groupId>org.jenkins-ci.plugins</groupId>
     <artifactId>apache-httpcomponents-client-5-api</artifactId>
-    <version>5.2.1-1.0</version>
   </dependency>
   <dependency>
     <artifactId>somelibrary-using-httpclient</artifactId>
@@ -95,15 +101,16 @@ Add the dependency to `apache-httpcomponents-client-5-api` *before* any of depen
 
 == Versioning
 
-Version follows the pattern of `<org.apache.httpcomponents version>-<plugin version>`.
-
+Version follows the pattern of `<org.apache.httpcomponents.client5 version>-<plugin version>`.
 This way it is clear what upstream dependency is offered and allows patch releases for the plugin itself if required.
 
+Since `org.apache.httpcomponents.client5` artifacts have a release cycle that is independent from `org.apache.httpcomponents.core5` artifacts, the latter part of patch releases for this plugin.
+
 == Release Notes
 
 Release notes are recorded in https://github.com/jenkinsci/apache-httpcomponents-client-5-api-plugin/releases[GitHub Releases].
 
 == License
 
-* https://opensource.org/licenses/MIT[MIT License] - Plugin codebase
-* https://www.apache.org/licenses/LICENSE-2.0[Apache License 2.0] - Nested library
+* Plugin source and documentation - https://opensource.org/licenses/MIT[MIT License]
+* Nested library - https://www.apache.org/licenses/LICENSE-2.0[Apache License 2.0]

pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
@@ -15,16 +16,19 @@
     <packaging>hpi</packaging>
 
     <properties>
-        <revision>5.2.3</revision>
+        <httpclient.version>5.2.1</httpclient.version>
+        <httpcore.version>5.2.3</httpcore.version>
+
+        <revision>${httpclient.version}</revision>
         <changelist>-999999-SNAPSHOT</changelist>
         <jenkins.version>2.361.4</jenkins.version>
-        <httpcore.version>${revision}</httpcore.version>
-        <httpclient.version>5.2.1</httpclient.version>
+
         <gitHubRepo>jenkinsci/apache-httpcomponents-client-5-api-plugin</gitHubRepo>
     </properties>
 
     <name>Apache HttpComponents Client 5.x API Plugin</name>
-    <description>Bundles Apache HttpComponents Client ${revision} and allows it to be used by Jenkins plugins</description>
+    <description>Bundles Apache HttpComponents Client ${revision} and allows it to be used by Jenkins plugins
+    </description>
     <url>https://github.com/${gitHubRepo}</url>
 
     <licenses>