Reformat & extend comments on TransportVersion (#97171)

Reflows the text to a width of 140, and adds a section about avoiding
inappropriate uses of `TransportVersion`.

Author: DaveCTurner

server/src/main/java/org/elasticsearch/TransportVersion.java

@@ -25,38 +25,43 @@
 import java.util.TreeMap;
 
 /**
- * Represents the version of the wire protocol used to communicate between ES nodes.
+ * Represents the version of the wire protocol used to communicate between a pair of ES nodes.
  * <p>
- * Prior to 8.8.0, the release {@link Version} was used everywhere. This class separates the wire protocol version
- * from the release version.
+ * Prior to 8.8.0, the release {@link Version} was used everywhere. This class separates the wire protocol version from the release version.
  * <p>
- * Each transport version constant has an id number, which for versions prior to 8.9.0 is the same as the release version
- * for backwards compatibility. In 8.9.0 this is changed to an incrementing number, disconnected from the release version.
+ * Each transport version constant has an id number, which for versions prior to 8.9.0 is the same as the release version for backwards
+ * compatibility. In 8.9.0 this is changed to an incrementing number, disconnected from the release version.
  * <p>
- * Each version constant has a unique id string. This is not actually used in the binary protocol, but is there to ensure
- * each protocol version is only added to the source file once. This string needs to be unique (normally a UUID,
- * but can be any other unique nonempty string).
- * If two concurrent PRs add the same transport version, the different unique ids cause a git conflict, ensuring the second PR to be merged
- * must be updated with the next free version first. Without the unique id string, git will happily merge the two versions together,
- * resulting in the same transport version being used across multiple commits,
- * causing problems when you try to upgrade between those two merged commits.
+ * Each version constant has a unique id string. This is not actually used in the binary protocol, but is there to ensure each protocol
+ * version is only added to the source file once. This string needs to be unique (normally a UUID, but can be any other unique nonempty
+ * string). If two concurrent PRs add the same transport version, the different unique ids cause a git conflict, ensuring that the second PR
+ * to be merged must be updated with the next free version first. Without the unique id string, git will happily merge the two versions
+ * together, resulting in the same transport version being used across multiple commits, causing problems when you try to upgrade between
+ * those two merged commits.
  * <h2>Version compatibility</h2>
- * The earliest compatible version is hardcoded in the {@link #MINIMUM_COMPATIBLE} field. Previously, this was dynamically calculated
- * from the major/minor versions of {@link Version}, but {@code TransportVersion} does not have separate major/minor version numbers.
- * So the minimum compatible version is hard-coded as the transport version used by the highest minor release of the previous major version.
- * {@link #MINIMUM_COMPATIBLE} should be updated appropriately whenever a major release happens.
+ * The earliest compatible version is hardcoded in the {@link #MINIMUM_COMPATIBLE} field. Previously, this was dynamically calculated from
+ * the major/minor versions of {@link Version}, but {@code TransportVersion} does not have separate major/minor version numbers. So the
+ * minimum compatible version is hard-coded as the transport version used by the highest minor release of the previous major version. {@link
+ * #MINIMUM_COMPATIBLE} should be updated appropriately whenever a major release happens.
  * <p>
- * The earliest CCS compatible version is hardcoded at {@link #MINIMUM_CCS_VERSION}, as the transport version used by the
- * previous minor release. This should be updated appropriately whenever a minor release happens.
+ * The earliest CCS compatible version is hardcoded at {@link #MINIMUM_CCS_VERSION}, as the transport version used by the previous minor
+ * release. This should be updated appropriately whenever a minor release happens.
  * <h2>Adding a new version</h2>
- * A new transport version should be added <em>every time</em> a change is made to the serialization protocol of one or more classes.
- * Each transport version should only be used in a single merged commit (apart from BwC versions copied from {@link Version}).
+ * A new transport version should be added <em>every time</em> a change is made to the serialization protocol of one or more classes. Each
+ * transport version should only be used in a single merged commit (apart from BwC versions copied from {@link Version}).
  * <p>
- * To add a new transport version, add a new constant at the bottom of the list that is one greater than the current highest version,
- * ensure it has a unique id, and update the {@link CurrentHolder#CURRENT} constant to point to the new version.
+ * To add a new transport version, add a new constant at the bottom of the list that is one greater than the current highest version, ensure
+ * it has a unique id, and update the {@link CurrentHolder#CURRENT} constant to point to the new version.
  * <h2>Reverting a transport version</h2>
- * If you revert a commit with a transport version change, you <em>must</em> ensure there is a <em>new</em> transport version
- * representing the reverted change. <em>Do not</em> let the transport version go backwards, it must <em>always</em> be incremented.
+ * If you revert a commit with a transport version change, you <em>must</em> ensure there is a <em>new</em> transport version representing
+ * the reverted change. <em>Do not</em> let the transport version go backwards, it must <em>always</em> be incremented.
+ * <h2>Scope of usefulness of {@link TransportVersion}</h2>
+ * {@link TransportVersion} is a property of the transport connection between a pair of nodes, and should not be used as an indication of
+ * the version of any single node. The {@link TransportVersion} of a connection is negotiated between the nodes via some logic that is not
+ * totally trivial, and may change in future. Any other places that might make decisions based on this version effectively have to reproduce
+ * this negotiation logic, which would be fragile. If you need to make decisions based on the version of a single node, do so using a
+ * different version value. If you need to know whether the cluster as a whole speaks a new enough {@link TransportVersion} to understand a
+ * newly-added feature, use {@link org.elasticsearch.cluster.ClusterState#getMinTransportVersion}.
  */
 public record TransportVersion(int id) implements Comparable<TransportVersion> {