[Documentation] Add section on version-specific features (SE-0135).

Author: ddunbar

Documentation/Usage.md

@@ -11,6 +11,7 @@
   * [Build an Executable](#build-an-executable)
   * [Create a Package](#create-a-package)
   * [Distribute a Package](#distribute-a-package)
+  * [Handling version-specific logic](#version-specific-logic)
 * [Reference](Reference.md)
 * [Resources](Resources.md)
 
@@ -323,3 +324,76 @@ import Foundation
 ## Distribute a Package
 
 *Content to come.*
+
+## Handling version-specific logic
+
+The package manager is designed to support packages which work with a variety of
+Swift project versions, including both the language and the package manager version.
+
+In most cases, if you want to support multiple Swift versions in a package you
+should do so by using the language-specific version checks available in the
+source code itself. However, in some circumstances this may become
+unmanageable; in particular, when the package manifest itself cannot be written
+to be Swift version agnostic (for example, because it optionally adopts new
+package manager features not present in older versions).
+
+The package manager has support for a mechanism to allow Swift version-specific
+customizations for the both package manifest and the package versions which will
+be considered.
+
+### Version-specific tag selection
+
+The tags which define the versions of the package available for clients to use
+can _optionally_ be suffixed with a marker in the form of `@swift-3`. When the
+package manager is determining the available tags for a repository, _if_ a
+version-specific marker is available which matches the current tool version,
+then it will *only* consider the versions which have the version-specific
+marker. Conversely, version-specific tags will be ignored by any non-matching
+tool version.
+
+For example, suppose the package `Foo` has the tags
+`[1.0.0, 1.2.0@swift-3, 1.3.0]`. If version 3.0 of the package manager is
+evaluating the available versions for this repository, it will only ever
+consider version `1.2.0`. However, version 4.0 would consider only `1.0.0` and
+`1.3.0`.
+
+This feature is intended for use in the following scenarios:
+
+1. A package wishes to maintain support for Swift 3.0 in older versions, but
+   newer versions of the package require Swift 4.0 for the manifest to be
+   readable. Since Swift 3.0 will not know to ignore those versions, it would
+   fail when performing dependency resolution on the package if no action is
+   taken. In this case, the author can re-tag the last versions which supported
+   Swift 3.0 appropriately.
+
+2. A package wishes to maintain dual support for Swift 3.0 and Swift 4.0 at the
+   same version numbers, but this requires substantial differences in the
+   code. In this case, the author can maintain parallel tag sets for both
+   versions.
+
+It is *not* expected the packages would ever use this feature unless absolutely
+necessary to support existing clients. In particular, packages *should not*
+adopt this syntax for tagging versions supporting the _latest GM_ Swift version.
+
+The package manager supports looking for any of the following marked tags, in
+order of preference:
+
+1. `MAJOR.MINOR.PATCH` (e.g., `[email protected]`)
+2. `MAJOR.MINOR` (e.g., `[email protected]`)
+3. `MAJOR` (e.g., `1.2.0@swift-3`)
+
+### Version-specific manifest selection
+
+The package manager will additionally look for a version-specific marked
+manifest version when loading the particular version of a package, by searching
+for a manifest in the form of `[email protected]`. The set of markers looked
+for is the same as for version-specific tag selection.
+
+This feature is intended for use in cases where a package wishes to maintain
+compatibility with multiple Swift project versions, but requires a substantively
+different manifest file for this to be viable (e.g., due to changes in the
+manifest API).
+
+It is *not* expected the packages would ever use this feature unless absolutely
+necessary to support existing clients. In particular, packages *should not*
+adopt this syntax for tagging versions supporting the _latest GM_ Swift version.