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