opensource.google.com

Menu

Docs

The One Version Rule

go/oneversion

Why can there be only one version of a library in //third_party?

The transitive dependencies of the google3 build system mean that if there are two versions present, eventually someone will try to build a project that depends on both versions. Untangling this after the fact can be very time consuming. Worse, it can stop a project dead that was not involved in submitting either version.

Example of how a project breaks (A→B means A “depends on” B):

Initial dependencies: Project A depends indirectly on third_party/FooV1 and
Project C

Now suppose that:

  1. FooV2 is added to third_party and made the “default” version, and
  2. Project C starts using FooV2 (and correctly selects the default V2)

New dependencies: Now Project C depends on
third_party/FooV2

Project A just broke. It depends on two different versions of Foo and will select a random one at runtime.

Both Project A and Project C followed the rules, yet one of them now needs to stop and resolve the multiple version issue. Depending on the upgrade and possibly chaining version issues, this can take days or weeks. In C++ this shows up as a static link failure. In Java, this shows up as both versions of Foo being present on project A’s classpath and a random version being used at runtime.

In short, google3 depends on there being exactly one version of every dependency.

When we allowed versioned directories (.../v1_20/...) we found people would think it was okay to have multiple versions. This is why we have since changed the policy and don’t even allow versioned directories (except for Java and Haskell, which have special infrastructure in place for this kind of thing).

Asking for temporary exceptions

We typically do not grant exceptions to the one version policy. It’s part of the maintainability tax for benefitting from google3. That said, if you need a temporary exception so that you can migrate all of google3 to a single new version, please do the following. We grant exceptions in cases where migration will take longer than a month. If migration will take less than a month, just get started and notify us on emailremoved@.

  1. Create a doc describing your plan to migrate everyone to your version and remove the duplicate. Include a reasonable time and staffing estimate. This is usually one quarter for software projects and two quarters for hardware projects, but it can vary based on context.

  2. Get the doc signed off by your director. Send an email asking for the temporary exception to emailremoved@. Link to the document and cc your director.

  3. Wait for confirmation on that thread by a emailremoved@ owner before you proceed.

Except as otherwise noted, the content of this page is licensed under CC-BY-4.0 license. Third-party product names and logos may be the trademarks of their respective owners.