Skip to content

Latest commit

 

History

History
250 lines (203 loc) · 7.57 KB

VENDORING.md

File metadata and controls

250 lines (203 loc) · 7.57 KB
Raw

Performing vendoring for the Kata Containers project

Vendoring tool

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 for details.

How to install and update dep

Install or update this tool using the following command:

$ go get -u github.com/golang/dep/cmd/dep

Make sure your PATH contains $GOPATH/bin:

$ 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.

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:

$ 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:

# 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"
#
# [prune]
#   non-go = false
#   go-tests = true
#   unused-packages = true

This file contains all the information you need to modify it properly.

At this point you can vendor any package needed from your code.

Pruning non-go files

dep provides the feature to remove all non-go files from your vendor tree during its prune phase. By default this is not enabled, but generally for Kata Containers repositories, we do enable this feature. If possible, modify your [prune] section to enable this feature:

 [prune]
   non-go = true
   go-tests = true
   unused-packages = true

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):

$ dep ensure

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:

[[constraint]]
  name = "github.com/foo/bar"
  revision = "f5742cb6"

Or, if you want to point to a specific version 1.2.4:

[[constraint]]
  name = "github.com/foo/bar"
  version = "1.2.4"

Or, if you want to point to a specific branch work-dev:

[[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:

[[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:

--- 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:

$ dep ensure

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:

$ dep ensure

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:

--- 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:

--- 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.

Miscellaneous

For additional information about vendoring, see "Re-vendor PRs".