github.com/stuarqi/moby@v1.13.1/VENDORING.md (about)

     1  # Vendoring policies
     2  
     3  This document outlines recommended Vendoring policies for Docker repositories.
     4  (Example, libnetwork is a Docker repo and logrus is not.)
     5  
     6  ## Vendoring using tags
     7  
     8  Commit ID based vendoring provides little/no information about the updates
     9  vendored. To fix this, vendors will now require that repositories use annotated
    10  tags along with commit ids to snapshot commits. Annotated tags by themselves
    11  are not sufficient, since the same tag can be force updated to reference
    12  different commits.
    13  
    14  Each tag should:
    15  - Follow Semantic Versioning rules (refer to section on "Semantic Versioning")
    16  - Have a corresponding entry in the change tracking document.
    17  
    18  Each repo should:
    19  - Have a change tracking document between tags/releases. Ex: CHANGELOG.md,
    20  github releases file.
    21  
    22  The goal here is for consuming repos to be able to use the tag version and
    23  changelog updates to determine whether the vendoring will cause any breaking or
    24  backward incompatible changes. This also means that repos can specify having
    25  dependency on a package of a specific version or greater up to the next major
    26  release, without encountering breaking changes.
    27  
    28  ## Semantic Versioning
    29  Annotated version tags should follow Schema Versioning policies.
    30  According to http://semver.org:
    31  
    32  "Given a version number MAJOR.MINOR.PATCH, increment the:
    33      MAJOR version when you make incompatible API changes,
    34      MINOR version when you add functionality in a backwards-compatible manner, and
    35      PATCH version when you make backwards-compatible bug fixes.
    36  Additional labels for pre-release and build metadata are available as extensions
    37  to the MAJOR.MINOR.PATCH format."
    38  
    39  ## Vendoring cadence
    40  In order to avoid huge vendoring changes, it is recommended to have a regular
    41  cadence for vendoring updates. e.g. monthly.
    42  
    43  ## Pre-merge vendoring tests
    44  All related repos will be vendored into docker/docker.
    45  CI on docker/docker should catch any breaking changes involving multiple repos.