From 581f72733ce44970088acebf20a019255cf35008 Mon Sep 17 00:00:00 2001 From: Sebastien Boeuf Date: Mon, 22 Jan 2018 15:09:07 -0800 Subject: [PATCH] docs: Explain vendoring with dep tool This commit introduces some new documentation about how to vendor when using dep tool. All this documentation is gathered in a new file called VENDORING.md Fixes #14 Signed-off-by: Sebastien Boeuf --- CONTRIBUTING.md | 3 + VENDORING.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 VENDORING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f693cc3bc..bb4ae9db3 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/VENDORING.md b/VENDORING.md new file mode 100644 index 000000000..6b2049ab5 --- /dev/null +++ b/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)".