docs: add vendoring tools information

[grahamwhaley]

To help devs with contributions, we should document which golang vendoring tools we use. Given the presence of https://github.com/clearcontainers/runtime/blob/master/Gopkg.lock I am guessing we use https://github.com/golang/dep. We could add the info either to the CONTRIB docs or the developer getting started guide I suspect.

[sboeuf]

Use github.com/golang/dep commit 24c37f5f336ec108d44e88a6f36125ab93c79951

[wcwxyz]

It's nice to document how to use dep to import a new go project as development guidelines.

[jodh-intel]

+1. I think we need atleast 2 examples:

• How to add a new dependency on the runtime with vendoring.
• How to make changes to both virtcontainers and the runtime and update the vendoring.

[grahamwhaley]

+1 @wcwxyz Right now @sboeuf is the master of dep afaict :-) If we gather info here then I am happy to do the PR for the docs. Things we should cover:

• we use dep built from a specific commit
• dep ensure
• dep prune
• do we have rules for tracking branch=master or other variants (version pinning) in the Gopkg.toml

[sboeuf]

Here is my email I had sent to our internal mailing list, there is nothing confidential, that's why I can copy/paste this here:

Hi folks,

I have recently updated the entire vendoring of virtcontainers and runtime, and that was a bit complicated but it is all sorted out now. I am glad to take care of the vendoring for the future, but I would like to share with you about what should be done in case I am not around and you really need to revendor.

First thing, it is very unlikely that you will need to revendor virtcontainers but this could happen in case some of our proxy/client API change.

Please use the tool version I used to prevent from any issue: github.com/golang/dep commit 24c37f5f336ec108d44e88a6f36125ab93c79951
This is very important so that we don't break the vendoring because they broke the backward compatibility with their recent commits.

If we want to move to a more recent commit, I think we could do that every month or so, the tool is working pretty well now, I don't see any reason to try to follow their master branch.

About the vendoring itself, most of the dependencies listed in Gopkg.toml and Gopkg.lock are constrained to master. This means that in case you want to update the runtime with the latest virtcontainers version, here is what you do:

$ dep ensure -update github.com/containers/virtcontainers
This will update the commit revision corresponding to origin/master in this case.
$ dep ensure
This will pull all the new files corresponding to the new commit revision
$ dep prune
This will remove all unused files

Eventually, you get only the files that have been modified on virtcontainers repo since the last vendoring + Gopkg.lock + Gopkg.toml in your list of files to commit. Make sure you don't get weird things.

These are the basic things you need to know if you need to revendor.

[sboeuf]

@grahamwhaley to summarize:

• dep commit version is 24c37f5f336ec108d44e88a6f36125ab93c79951
• dep ensure: either we go with dep ensure github.com/our/new/pkg if that's the first time we vendor this package, or we use dep ensure -update github.com/our/new/pkg if we need a bump to a more recent version of this package.
• dep prune has to be run every time we use dep ensure ... in order to make sure we don't carry some unneeded dependencies.
• About the package versions that we want to follow, there are 3 points IMO. In case the package is a sub-dependency (another package used by a package that we vendor), we should not modify the default version setup by dep. In case the package needs to stay at a specific revision for compatibility reasons, otherwise it breaks our code (but we need good explanations for this). And for all other cases, we can pin the revision to master. This means that you can modify Gopkg.toml to constraint any package to follow master. Every time you will call in dep ensure -update ... the package will be updated to master.

[jodh-intel]

Note that the document should also state that if the re-vendoring removes any limitations, the author of that PR should also update https://github.com/clearcontainers/runtime/blob/master/docs/limitations.md (and in fact mention in the commit message that "limitation X" has been removed).