From b328f5114651349c38b723bca8e4a046ba02ec39 Mon Sep 17 00:00:00 2001 From: Benjamin Elder Date: Thu, 24 Apr 2025 20:07:53 -0700 Subject: [PATCH] delete defunct godeps docs > This document only applies to Kubernetes 1.14.x and earlier, and should be removed once Kubernetes 1.14.x is no longer supported. ... we're well past this --- contributors/devel/sig-architecture/godep.md | 268 +------------------ 1 file changed, 1 insertion(+), 267 deletions(-) diff --git a/contributors/devel/sig-architecture/godep.md b/contributors/devel/sig-architecture/godep.md index 1c17621f7..050096f8b 100644 --- a/contributors/devel/sig-architecture/godep.md +++ b/contributors/devel/sig-architecture/godep.md @@ -1,268 +1,2 @@ **Note**: Kubernetes now manages dependencies using go modules. -See [current documentation for working with dependencies](./vendor.md) for master branch development. -This document only applies to Kubernetes 1.14.x and earlier, -and should be removed once Kubernetes 1.14.x is no longer supported. - -# Using godep to manage dependencies - -This document is intended to show a way for managing `vendor/` tree dependencies -in Kubernetes. If you do not need to manage vendored dependencies, you probably -do not need to read this. - -## Background - -As a tool, `godep` leaves much to be desired. It builds on `go get`, and adds -the ability to pin dependencies to exact git version. The `go get` tool itself -doesn't have any concept of versions, and tends to blow up if it finds a git -repo synced to anything but `master`, but that is exactly the state that -`godep` leaves repos. This is a recipe for frustration when people try to use -the tools. - -This doc will focus on predictability and reproducibility. - -## Justifications for an update - -Before you update a dependency, take a moment to consider why it should be -updated. Valid reasons include: - 1. We need new functionality that is in a later version. - 2. New or improved APIs in the dependency significantly improve Kubernetes code. - 3. Bugs were fixed that impact Kubernetes. - 4. Security issues were fixed even if they don't impact Kubernetes yet. - 5. Performance, scale, or efficiency was meaningfully improved. - 6. We need dependency A and there is a transitive dependency B. - 7. Kubernetes has an older level of a dependency that is precluding being able -to work with other projects in the ecosystem. - -## Theory of operation - -The `go` toolchain assumes a global workspace that hosts all of your Go code. - -The `godep` tool operates by first "restoring" dependencies into your `$GOPATH`. -This reads the `Godeps.json` file, downloads all of the dependencies from the -internet, and syncs them to the specified revisions. You can then make -changes - sync to different revisions or edit Kubernetes code to use new -dependencies (and satisfy them with `go get`). When ready, you tell `godep` to -"save" everything, which it does by walking the Kubernetes code, finding all -required dependencies, copying them from `$GOPATH` into the `vendor/` directory, -and rewriting `Godeps.json`. - -This does not work well, when combined with a global Go workspace. Instead, we -will set up a private workspace for this process. - -The Kubernetes build process uses this same technique, and offers a tool called -`run-in-gopath.sh` which sets up and switches to a local, private workspace, -including setting up `$GOPATH` and `$PATH`. If you wrap commands with this -tool, they will use the private workspace, which will not conflict with other -projects and is easily cleaned up and recreated. - -To see this in action, you can run an interactive shell in this environment: - -```sh -# Run a shell, but don't run your own shell initializations. -hack/run-in-gopath.sh bash --norc --noprofile -``` - -## Restoring deps - -To extract and download dependencies into `$GOPATH` we provide a script: -`hack/godep-restore.sh`. If you run this tool, it will restore into your own -`$GOPATH`. If you wrap it in `run-in-gopath.sh` it will restore into your -`_output/` directory. - -```sh -hack/run-in-gopath.sh hack/godep-restore.sh -``` - -This script will try to optimize what it needs to download, and if it seems the -dependencies are all present already, it will return very quickly. - -If there's ever any doubt about the correctness of your dependencies, you can -simply `make clean` or `rm -rf _output`, and run it again. - -Now you should have a clean copy of all of the Kubernetes dependencies. - -Downloading dependencies might take a while, so if you want to see progress -information use the `-v` flag: - -```sh -hack/run-in-gopath.sh hack/godep-restore.sh -v -``` - -## Making changes - -The most common things people need to do with deps are add and update them. -These are similar but different. - -### Adding a dep - -For the sake of examples, consider that we have discovered a wonderful Go -library at `example.com/go/frob`. The first thing you need to do is get that -code into your workspace: - -```sh -hack/run-in-gopath.sh go get -d example.com/go/frob -``` - -This will fetch, but not compile (omit the `-d` if you want to compile it now), -the library into your private `$GOPATH`. It will pull whatever the default -revision of that library is, typically the `master` branch for git repositories. -If this is not the revision you need, you can change it, for example to -`v1.0.0`: - -```sh -hack/run-in-gopath.sh bash -c 'git -C $GOPATH/src/example.com/go/frob checkout v1.0.0' -``` - -Now that the code is present, you can start to use it in Kubernetes code. -Because it is in your private workspace's `$GOPATH`, it might not be part of -your own `$GOPATH`, so tools like `goimports` might not find it. This is an -unfortunate side-effect of this process. You can either add the whole private -workspace to your own `$GOPATH` or you can `go get` the library into your own -`$GOPATH` until it is properly vendored into Kubernetes. - -Another possible complication is a dep that uses `gopdep` itself. In that case, -you need to restore its dependencies, too: - -```sh -hack/run-in-gopath.sh bash -c 'cd $GOPATH/src/example.com/go/frob && godep restore' -``` - -If the transitive deps collide with Kubernetes deps, you may have to manually -resolve things. This is where the ability to run a shell in this environment -comes in handy: - -```sh -hack/run-in-gopath.sh bash --norc --noprofile -``` - -### Updating a dep - -Sometimes we already have a dep, but the version of it is wrong. Because of the -way that `godep` and `go get` interact (badly) it's generally easiest to hit it -with a big hammer: - -```sh -hack/run-in-gopath.sh bash -c 'rm -rf $GOPATH/src/example.com/go/frob' -hack/run-in-gopath.sh go get -d example.com/go/frob -hack/run-in-gopath.sh bash -c 'git -C $GOPATH/src/example.com/go/frob checkout v2.0.0' -``` - -This will remove the code, re-fetch it, and sync to your desired version. - -### Removing a dep - -This happens almost for free. If you edit Kubernetes code and remove the last -use of a given dependency, you only need to restore and save the deps, and the -`godep` tool will figure out that you don't need that dep any more: - -## Saving deps - -Now that you have made your changes - adding, updating, or removing the use of a -dep - you need to rebuild the dependency database and make changes to the -`vendor/` directory. - -```sh -hack/run-in-gopath.sh hack/godep-save.sh -``` - -This will run through all of the primary targets for the Kubernetes project, -calculate which deps are needed, and rebuild the database. It will also -regenerate other metadata files which the project needs, such as BUILD files and -the LICENSE database. - -Commit the changes before updating deps in staging repos. - -## Saving deps in staging repos - -Kubernetes stores some code in a directory called `staging` which is handled -specially, and is not covered by the above. If you modified any code under -staging, or if you changed a dependency of code under staging (even -transitively), you'll also need to update deps there: - -```sh -./hack/update-staging-godeps.sh -``` - -Then commit the changes generated by the above script. - -## Commit messages - -Terse messages like "Update foo.org/bar to 0.42" are problematic -for maintainability. Please include in your commit message the -detailed reason why the dependencies were modified. - -Too commonly dependency changes have a ripple effect where something -else breaks unexpectedly. The first instinct during issue triage -is to revert a change. If the change was made to fix some other -issue and that issue was not documented, then a revert simply -continues the ripple by fixing one issue and reintroducing another -which then needs refixed. This can needlessly span multiple days -as CI results bubble in and subsequent patches fix and refix and -rerefix issues. This may be avoided if the original modifications -recorded artifacts of the change rationale. - -## Sanity checking - -After all of this is done, `git status` should show you what files have been -modified and added/removed. Make sure to sanity-check them with `git diff`, and -to `git add` and `git rm` them, as needed. It is commonly advised to make one -`git commit` which includes just the dependencies and Godeps files, and -another `git commit` that includes changes to Kubernetes code to use (or stop -using) the new/updated/removed dependency. These commits can go into a single -pull request. - -Before sending your PR, it's a good idea to sanity check that your -Godeps.json file and the contents of `vendor/ `are ok: - -```sh -hack/run-in-gopath.sh hack/verify-godeps.sh -``` - -All this script will do is a restore, followed by a save, and then look for -changes. If you followed the above instructions, it should be clean. If it is -not, you get to figure out why. - -## Manual updates - -It is sometimes expedient to manually fix the `Godeps.json` file to -minimize the changes. However, without great care this can lead to failures -with the verifier scripts. The kubernetes codebase does "interesting things" -with symlinks between `vendor/` and `staging/` to allow multiple Go import -paths to coexist in the same git repo. - -The verifiers, including `hack/verify-godeps.sh` *must* pass for every pull -request. - -## Reviewing and approving dependency changes - -Particular attention to detail should be exercised when reviewing and approving -PRs that add/remove/update dependencies. Importing a new dependency should bring -a certain degree of value as there is a maintenance overhead for maintaining -dependencies into the future. - -When importing a new dependency, be sure to keep an eye out for the following: -- Is the dependency maintained? -- Does the dependency bring value to the project? Could this be done without - adding a new dependency? -- Is the target dependency the original source, or a fork? -- Is there already a dependency in the project that does something similar? -- Does the dependency have a license that is compatible with the Kubernetes - project? - -Additionally: -- Look at the godeps file. Check that the only changes are what the PR claims - them to be. -- Check if there is a tagged release we can vendor instead of a random hash -- Scan the imported code for things like init() functions -- Look at the Kubernetes code changes and make sure they are appropriate - (e.g. renaming imports or similar). You do not need to do feature code review. -- If this is all good, approve, but don't LGTM, unless you also do code review - or unless it is trivial (e.g. moving from k/k/pkg/utils -> k/utils). - -All new dependency licenses should be reviewed by @kubernetes/dep-approvers to ensure that they -are compatible with the Kubernetes project license. It is also important to note -and flag if a license has changed when updating a dependency, so that these can -also be reviewed. - -For reference, whitelisted licenses as per the CNCF Whitelist Policy are -mentioned [here](https://git.k8s.io/sig-release/licensing/README.md#licenses-for-dependencies). +See [current documentation for working with dependencies](./vendor.md) for master branch development. \ No newline at end of file