Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Adding a section on vendor vs. proxy to the FAQ #1340

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/content/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,3 +87,37 @@ Which currently includes:
- hg
- bzr
- fossil

### When should I use a vendor directory, and when should I use Athens?

The Go community has used vendor directories for a long time before module proxies like Athens came along, so naturally each group collaborating on code should decide for themselves whether they want to use a vendor directory, not use a vendor directory and just use Athens, or do both!

Vendor (without a proxy) valuable when:

- CI/CD systems don't have access to an Athens (even if it's internal)
- When vendor is so small, it's still faster to check it out from your repo than it is to pull zip files from the server
- If you're coming from glide/dep or another "older" dependency management system that leveraged the vendor directory

Athens valuable when:

- You have a new project
- You want to, or your system admin / CTO / etc.. requires, that you use Athens (i.e. for isolation or dependency auditing)
- Your vendor checkout speeds are getting "slow" (for some value of slow, IDK) and downloading from Athens speeds the build up

It was a combination of the following:

- waiting for 1.13 for better config (e.g. multiple values in GOPROXY & easier config for private modules)
- vendoring sped up the build more than using the google go proxy


I expect at that point it will be about the build time as we don't use any advanced features yet such as validation hooks or access control.

I think the speed benefits of Athens vary greatly depending on the context. if you’re a developer, you probably already have the vendor directory checked out, so Athens won’t beat that for sure. in CI/CD the story might be different if it has to check out vendor from source control on each run. in that case, concurrently downloading some zip files over a (fast-ish?) network is often faster than the checkout. sometimes the same goes for docker builds and copying the vendor directory into the build environment

For me, I think the value comes from guaranteed builds and less noise for the developer. To clarify, I assume in your context, it is the responsibility of the developer to check in the vendor folder. Otherwise, your CI/CD would need to run go mod vendor and would need to download the dependencies anyway. So if you put the responsibility on the developer to include the vendor folder, it's possible for them to modify the contents of vendor (which no one should do, but yeah, devs do silly things). I'd also think your PRs could get a little noisy when adding or removing packages as its no longer contained within your go.mod

We've had similar conversations relating to client stubs generated from .proto files for Go gRPC services. Do developers maintain their own copy of generated stubs in their project, or just depend on a known distributed set of clients. We chose the latter as we didn't want devs messing with the client definitions and felt it was a better overall experience

@Fraser the developers also benefit from athens since they don't have to clone all dependencies each time they clone the git repo. Personally I have loads of different folders with the same repo, but different branches. If I had to have (in our case) ~200 dependencies in each of them it would be more painful than today