Merge pull request #15 from sboeuf/add_vendoring_docs

docs: Explain vendoring with dep tool

CONTRIBUTING.md

@@ -129,6 +129,9 @@ body:
   GitHub to render the list in a fixed-width font, which makes it easier to
   read.
 
+For additional information on using the `dep` tool, see
+"[Performing vendoring for the Kata Containers project](https://github.com/kata-containers/community/blob/master/VENDORING.md)".
+
 ## Patch format
 
 Beside the `Signed-off-by` footer, we expect each patch to comply with the

VENDORING.md

@@ -0,0 +1,232 @@
+# Performing vendoring for the Kata Containers project
+
+* [Vendoring tool](#vendoring-tool)
+    * [How to install and update dep](#how-to-install-and-update-dep)
+    * [Overview of the main commands](#overview-of-the-main-commands)
+* [Vendoring use cases](#vendoring-use-cases)
+    * [Initialize vendoring of the package](#initialize-vendoring-of-the-package)
+    * [Vendor a newly imported package](#vendor-a-newly-imported-package)
+    * [Update a vendored package](#update-a-vendored-package)
+    * [Remove a vendored package](#remove-a-vendored-package)
+    * [Test a pending pull request](#test-a-pending-pull-request)
+* [Miscellaneaous](#miscellaneaous)
+
+## Vendoring tool
+
+[`dep`](https://github.com/golang/dep) is the vendoring tool chosen for this
+project because it is simple and powerful for some corner cases. Furthermore,
+this tool is expected to be the official vendoring tool for Golang.
+
+Ensure you use the latest version of the `dep` tool. See 
+[How to install and update dep](#how-to-install-and-update-dep) for details.
+
+### How to install and update dep
+
+Install or update this tool using the following command:
+```bash
+$ go get -u github.com/golang/dep/cmd/dep
+```
+
+Make sure your `PATH` contains `$GOPATH/bin`:
+```bash
+$ export PATH=$GOPATH/bin:$PATH
+```
+
+### Overview of the main commands
+
+- `dep init`: Initialize a new project with manifest and lock files.
+- `dep ensure`: Ensure a dependency is safely vendored in the project.
+- `dep prune`: Prune the vendor tree of unused packages.
+
+## Vendoring use cases
+
+Here will be listed the different vendoring use cases a developer could
+encounter when developing for Kata Containers.
+
+### Initialize vendoring of the package
+
+If no prior vendoring has been performed on the package, you need to
+initialize it with the following command:
+```bash
+$ dep init
+```
+
+This should create a new directory named `vendor` at the root of your
+package, and two new files to manage the vendoring (i.e. `Gopkg.toml`
+and `Gopkg.lock`).
+
+`Gopkg.lock` is automatically re-generated by `dep` every time a new
+`dep ensure` command is issued. This file should not be modified by the
+developer.
+`Gopkg.toml` is automatically generated by `dep init` and can be modified
+in order to add a constraint on a package to follow a specific revision.
+
+The following is what `Gopkg.toml` should look like:
+```toml
+# Gopkg.toml example
+#
+# Refer to https://github.com/golang/dep/blob/master/docs/Gopkg.toml.md
+# for detailed Gopkg.toml documentation.
+#
+# required = ["github.com/user/thing/cmd/thing"]
+# ignored = ["github.com/user/project/pkgX", "bitbucket.org/user/project/pkgA/pkgY"]
+#
+# [[constraint]]
+#   name = "github.com/user/project"
+#   version = "1.0.0"
+#
+# [[constraint]]
+#   name = "github.com/user/project2"
+#   branch = "dev"
+#   source = "github.com/myfork/project2"
+#
+# [[override]]
+#  name = "github.com/x/y"
+#  version = "2.4.0"
+
+```
+This file contains all the information you need to modify it properly.
+
+At this point you can vendor any package needed from your code.
+
+### Vendor a newly imported package
+
+The following case describes a situation when you add new code that relies
+on a package that has never been imported (e.g. `github.com/foo/bar`):
+```bash
+$ dep ensure
+$ dep prune
+```
+
+At this point, only the required files will be copied into `vendor`.
+
+Additionally, you might want to ensure the vendored package refers to a
+specific version. This is called a constraint with `dep`. By modifying
+`Gopkg.toml`, you can decide to force the package `github.com/foo/bar` to
+point to the revision `f5742cb6`. The following is what the file should look
+like:
+```toml
+[[constraint]]
+  name = "github.com/foo/bar"
+  revision = "f5742cb6"
+```
+
+Or, if you want to point to a specific version `1.2.4`:
+```toml
+[[constraint]]
+  name = "github.com/foo/bar"
+  version = "1.2.4"
+```
+
+Or, if you want to point to a specific branch `work-dev`:
+```toml
+[[constraint]]
+  name = "github.com/foo/bar"
+  branch = "work-dev"
+```
+
+Lastly, a powerful constraint is to specify if the source of the repository
+comes from a forked repository:
+```toml
+[[constraint]]
+  name = "github.com/foo/bar"
+  branch = "fork-work-dev"
+  source = "github.com/myfork/bar"
+```
+
+__Note:__ Constraining a package is important because this is the only way to
+be certain of the imported package version. This prevents any build failure
+that could result from a package change on the upstream.
+
+### Update a vendored package
+
+The following case describes a situation where you add some code that relies
+on another version of a package already vendored. This is a simple case since
+the package is already part of the vendoring. You modify `Gopkg.toml` by
+updating the vendoring version:
+
+```diff
+--- Gopkg.toml.orig     2018-01-23 09:04:54.160760426 -0800
++++ Gopkg.toml.new      2018-01-23 09:05:09.164094911 -0800
+@@ -1,3 +1,3 @@
+ [[constraint]]
+   name = "github.com/foo/bar"
+-  revision = "f5742cb6"
++  revision = "a4be45c7"
+```
+
+Let `dep` update the vendoring by relying on this new revision:
+```bash
+$ dep ensure
+$ dep prune
+```
+
+### Remove a vendored package
+
+The following case describes a situation where you modify the existing
+code, no longer relying on a vendored package. Running the usual commands
+removes the vendored package from `vendor` directory and from
+`Gopkg.lock`:
+```bash
+$ dep ensure
+$ dep prune
+```
+
+If a constraint is set in `Gopkg.toml`, it is your responsibility to remove
+the constraint manually from the file.
+
+### Test a pending pull request
+
+The following case describes a situation where you need to perform testing
+on your code due to a pending pull request from a vendored package.
+The easiest and safest way to do that is to rely on a feature proposed
+by `dep` called `override`. This feature allows you to leave the constraints
+unmodified, but relies on a different version of the vendored package for
+testing purposes.
+
+#### From the main repository
+
+The pending pull request can be submitted to the main repository through a
+development branch `work-dev`. In this case, you will need to modify
+`Gopkg.toml` as follows:
+
+```diff
+--- Gopkg.toml.orig     2018-01-23 09:04:54.160760426 -0800
++++ Gopkg.toml.new      2018-01-23 09:06:49.735633780 -0800
+@@ -1,3 +1,7 @@
+ [[constraint]]
+   name = "github.com/foo/bar"
+   revision = "f5742cb6"
++
++[[override]]
++  name = "github.com/foo/bar"
++  branch = "work-dev"
+```
+
+#### From a forked repository
+
+The pending pull request can be submitted to a forked repository through a
+development branch called `work-dev`. In this case you will need to modify
+`Gopkg.toml` as follows:
+
+```diff
+--- Gopkg.toml.orig     2018-01-23 09:04:54.160760426 -0800
++++ Gopkg.toml.new      2018-01-23 09:09:58.475261707 -0800
+@@ -1,3 +1,8 @@
+ [[constraint]]
+   name = "github.com/foo/bar"
+   revision = "f5742cb6"
++
++[[override]]
++  name = "github.com/foo/bar"
++  branch = "work-dev"
++  source = "github.com/myfork/bar"
+```
+
+The previous case is more common because typically you do not have permissions
+to push directly to the main repository.
+
+## Miscellaneaous
+
+For additional information about vendoring, see
+"[Re-vendor PRs](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#re-vendor-prs)".