Merge pull request #8436 from BenTheElder/no-godeps

delete defunct godeps docs
2025-04-24 20:20:31 -07:00 · 2025-04-24 20:20:31 -07:00 · c9f4e7e868
parent b3de0387c5 b328f51146
commit c9f4e7e868
1 changed files with 1 additions and 267 deletions
--- 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.
+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).