Onboarding: google/guava

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Single-maintainer risk — top contributor 91% of commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

Google Guava is a battle-tested set of core Java libraries that extends the JDK with new collection types (Multimap, Multiset, BiMap, Table, RangeMap), immutable collection implementations, a graph/network library, and utilities for concurrency (ListenableFuture, RateLimiter), hashing (BloomFilter, Hashing), I/O, primitives, and Strings. It ships in two flavors: a JRE flavor (Java 8+) under guava/ and an Android-compatible flavor under android/guava/, both built from the same source with conditional compilation via @GwtCompatible and @GwtIncompatible annotations. The repo is a Maven multi-module monorepo: guava/ holds the JRE production sources, android/guava/ holds the Android-equivalent sources (symlinked or duplicated), guava-testlib/ and android/guava-testlib/ contain reusable test suite infrastructure (e.g., AbstractCollectionTester, FeatureSpecificTestSuiteBuilder), and guava-tests/ contains the actual test cases. The android/ subtree mirrors the top-level structure for Android-targeted builds.

Who it's for

Java backend engineers and Android developers who need robust, well-tested utility APIs beyond what the JDK provides — particularly those working on large-scale server-side Java at Google or in enterprises who want immutable-by-default collections, functional-style collection transforms, and concurrent primitives without rolling their own.

Maturity & risk

Guava is one of the most mature Java libraries in existence — it has been in active development since 2010, is at version 33.6.0, has extensive JUnit-based test suites under guava-tests/ and guava-testlib/, and runs CI via GitHub Actions (.github/workflows/ci.yml). It is unambiguously production-ready and is used in virtually every Java project at Google.

Risk is extremely low: Guava is maintained by Google engineers with a long public track record and the BOM (guava-bom/) ensures consistent versioning across artifacts. The main non-trivial risk is API churn around @Beta-annotated APIs, which Google does occasionally remove. The dual JRE/Android flavor adds complexity — code changes must be verified not to break Android compatibility.

Active areas of work

Based on the repo structure and CI configuration in .github/workflows/ci.yml and scorecard.yml, active work includes maintaining both JRE and Android flavor parity, dependency updates managed via .github/dependabot.yml, and the snapshot version 999.0.0-HEAD-android-SNAPSHOT indicating ongoing HEAD snapshot publishing. The BOM pom.xml reflects active artifact lifecycle management.

Get running

git clone https://github.com/google/guava.git cd guava

Build everything (requires JDK 8+ for Android flavor, JDK 11+ recommended)

./mvnw install -DskipTests

Run tests for the JRE flavor

./mvnw test -pl guava-tests

Run tests for Android flavor

./mvnw test -pl android/guava-tests

Daily commands: ./mvnw test -pl guava-tests # JRE flavor tests ./mvnw test -pl android/guava-tests # Android flavor tests ./mvnw install -DskipTests # Build all modules without running tests

Map of the codebase

• android/guava-testlib/src/com/google/common/collect/testing/FeatureSpecificTestSuiteBuilder.java — Core framework for building parameterized test suites based on collection features — the backbone of guava-testlib's testing infrastructure.
• android/guava-testlib/src/com/google/common/collect/testing/AbstractIteratorTester.java — Foundational abstract class for iterator contract verification, used across all collection iterator tests in the testlib.
• android/guava-testlib/src/com/google/common/collect/testing/features/FeatureUtil.java — Utility class that resolves which test methods to run based on declared feature annotations — critical to the feature-driven test dispatch model.
• android/guava-testlib/src/com/google/common/collect/testing/MapTestSuiteBuilder.java — Primary entry point for generating comprehensive Map contract test suites; widely referenced by downstream modules.
• android/guava-testlib/src/com/google/common/collect/testing/AbstractContainerTester.java — Base class for all container (collection/map) testers, establishing the shared state and helper contract every tester builds upon.
• android/guava-bom/pom.xml — Bill of Materials POM that defines canonical versions for all Guava artifacts — must be understood before adding or changing module dependencies.
• android/guava-testlib/src/com/google/common/collect/testing/SpliteratorTester.java — Verifies Spliterator contracts for collections; critical for ensuring Java 8+ stream compatibility across all Guava collection types.

How to make changes

Add a new Guava collection tester (e.g. for a new Multimap type)

1. Define the feature enum values your new collection supports by adding entries to the appropriate feature enum or creating a new one. (android/guava-testlib/src/com/google/common/collect/testing/features/CollectionFeature.java)
2. Create a new abstract tester class extending AbstractContainerTester (or the most specific applicable base) and annotate test methods with @CollectionFeature.Require. (android/guava-testlib/src/com/google/common/collect/testing/AbstractContainerTester.java)
3. Create a TestSubjectGenerator implementation (e.g. extending TestStringCollectionGenerator) that knows how to build instances of your new collection from a sample array. (android/guava-testlib/src/com/google/common/collect/testing/TestStringCollectionGenerator.java)
4. Create a new TestSuiteBuilder (extending FeatureSpecificTestSuiteBuilder) that registers your tester class and wires it to the generator and feature set. (android/guava-testlib/src/com/google/common/collect/testing/FeatureSpecificTestSuiteBuilder.java)

Add a new Map feature test (e.g. testing SUPPORTS_PUT_ALL)

1. Add or verify the feature constant exists in MapFeature enum, used to gate test execution. (android/guava-testlib/src/com/google/common/collect/testing/features/MapFeature.java)
2. Add the new test method to AbstractMapTester or an appropriate subclass, annotated with @MapFeature.Require(MapFeature.SUPPORTS_PUT_ALL). (android/guava-testlib/src/com/google/common/collect/testing/AbstractMapTester.java)
3. Register the new tester class in MapTestSuiteBuilder so the suite builder includes it when constructing test suites. (android/guava-testlib/src/com/google/common/collect/testing/MapTestSuiteBuilder.java)

Add a new collection size test scenario

1. Review CollectionSize feature enum to understand existing size constraints (ZERO, ONE, SEVERAL) and add a new entry if needed. (android/guava-testlib/src/com/google/common/collect/testing/features/CollectionSize.java)
2. Update PerCollectionSizeTestSuiteBuilder to handle the new size variant and generate appropriately sized sample data. (android/guava-testlib/src/com/google/common/collect/testing/PerCollectionSizeTestSuiteBuilder.java)
3. Update SampleElements or create a new generator that produces the required number of distinct test elements. (android/guava-testlib/src/com/google/common/collect/testing/SampleElements.java)

Integrate guava-testlib to test a custom Map implementation

1. Implement TestStringMapGenerator (or TestMapGenerator<K,V>) to construct instances of your custom Map from a given entries array. (android/guava-testlib/src/com/google/common/collect/testing/TestStringMapGenerator.java)
2. Use MapTestSuiteBuilder.using(yourGenerator).withFeatures(...) to

Traps & gotchas

1. The android/ flavor must maintain Java 7 API compatibility (no lambdas, no streams in production code) even though the JRE flavor targets Java 8+ — this is a constant source of confusion. 2) Signing artifacts for Maven Central requires GPG keys configured via maven-gpg-plugin — local builds skip this with -DskipTests but release builds do not. 3) The maven-wrapper (./mvnw) must be used rather than a system Maven installation to ensure the pinned version from .mvn/wrapper/maven-wrapper.properties is used. 4) Many APIs annotated @Beta can be removed without a deprecation cycle — never depend on @Beta APIs in downstream libraries.

Concepts to learn

• Immutable Collections — Guava's ImmutableList, ImmutableMap, ImmutableSet etc. are not just unmodifiable wrappers — they are truly immutable with defensive copying, thread-safety guarantees, and optimized memory layouts that the JDK's Collections.unmodifiableXxx() do not provide.
• Bloom Filter — Guava ships a production-quality probabilistic data structure (com.google.common.hash.BloomFilter) for approximate set membership testing with configurable false positive rates — understanding the math behind it is essential for using it correctly.
• ListenableFuture — Guava's ListenableFuture (com.google.common.util.concurrent) extends Java's Future with callback registration, enabling non-blocking async composition before CompletableFuture existed — large portions of Google's internal Java codebase still use it.
• Multimap — Guava's Multimap allows mapping a single key to multiple values (e.g., ArrayListMultimap, SetMultimap) — a common pattern that otherwise requires Map<K, List<V>> with error-prone null-initialization boilerplate.
• Token Bucket Rate Limiting — Guava's RateLimiter (com.google.common.util.concurrent.RateLimiter) implements the token bucket / leaky bucket algorithm for smooth or bursty rate limiting — understanding the algorithm is necessary to configure it for real traffic patterns.
• Consistent Hashing — Guava's Hashing.consistentHash() implements the ring-based consistent hashing algorithm used in distributed systems for stable key-to-shard assignment — a non-obvious advanced use of the Hashing utility class.
• Parameterized Collection Contract Testing — guava-testlib's FeatureSpecificTestSuiteBuilder pattern lets you declare which features (e.g., SUPPORTS_ADD, ALLOWS_NULL_VALUES) your collection supports and automatically generates the correct subset of contract tests — this is the architectural pattern underpinning all of Guava's collection correctness guarantees.

Related repos

• apache/commons-lang — Apache Commons Lang is the closest alternative providing similar string, array, and general Java utility APIs in the same JVM ecosystem.
• eclipse-collections/eclipse-collections — Eclipse Collections is an alternative rich collection library for Java with mutable and immutable variants, directly competing with Guava's collection extensions.
• google/error-prone — Error Prone is used by the Guava team for static analysis; many Guava APIs are designed around Error Prone's nullness and concurrency checkers.
• google/guava-testlib — guava-testlib is actually embedded in this monorepo but published separately — external projects use it to test their own collection implementations against Guava's contract test suites.
• JodaOrg/joda-time — Predecessor inspiration: Joda-Time filled a similar 'JDK is insufficient' niche for date/time before JSR-310, the same motivation that drove Guava's creation for collections and utilities.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add ConcurrentNavigableMap test suite coverage to android/guava-testlib

The file android/guava-testlib/src/com/google/common/collect/testing/ConcurrentNavigableMapTestSuiteBuilder.java exists but there is no corresponding ConcurrentNavigableMap-specific tester class visible in the file listing (unlike ConcurrentMapTestSuiteBuilder which pairs with concrete map testers). Adding dedicated feature-specific testers for concurrent navigable map operations (e.g., headMap, tailMap, subMap under concurrent access) would improve correctness guarantees for ConcurrentSkipListMap-backed implementations and fill a visible gap in the test infrastructure.

• [ ] Review android/guava-testlib/src/com/google/common/collect/testing/ConcurrentNavigableMapTestSuiteBuilder.java to identify which test features are currently wired up vs. missing
• [ ] Compare with NavigableMapTestSuiteBuilder.java to find navigable-specific tester classes (e.g., for headMap/tailMap/subMap views) that are not duplicated for the concurrent variant
• [ ] Create new tester classes under android/guava-testlib/src/com/google/common/collect/testing/testers/ covering concurrent navigable operations such as concurrent iteration over subMap views
• [ ] Register the new tester classes in ConcurrentNavigableMapTestSuiteBuilder.java
• [ ] Mirror the same changes in the non-android guava-testlib module to keep both flavors in sync
• [ ] Run the existing test suite to confirm no regressions and that new tests execute

Add SpliteratorTester coverage for android/guava-testlib collection generators

android/guava-testlib/src/com/google/common/collect/testing/SpliteratorTester.java exists but the visible generator files (TestEnumSetGenerator, TestEnumMapGenerator, TestCharacterListGenerator, TestCollidingSetGenerator, etc.) do not appear to have dedicated spliterator characteristic tests wired through the suite builders. Since Spliterator characteristics (SIZED, ORDERED, DISTINCT, SORTED, IMMUTABLE) are critical for correctness of Stream pipelines built on Guava collections, adding explicit spliterator characteristic assertions for each generator would catch subtle bugs.

• [ ] Audit SpliteratorTester.java to understand the existing API surface for asserting spliterator characteristics
• [ ] Review CollectionTestSuiteBuilder.java, SetTestSuiteBuilder.java, ListTestSuiteBuilder.java, and SortedSetTestSuiteBuilder.java to identify where spliterator tests are (or are not) injected
• [ ] For each collection generator (TestEnumSetGenerator, TestCollidingSetGenerator, TestCharacterListGenerator, etc.) define the expected Spliterator characteristics
• [ ] Add a new tester class, e.g., CollectionSpliteratorTester.java, that uses SpliteratorTester to assert correct characteristics and traversal behavior
• [ ] Wire CollectionSpliteratorTester into the relevant suite builders so it runs automatically for all registered generators
• [ ] Mirror changes in the JRE guava-testlib module and verify CI passes

Refactor duplicated abstract tester infrastructure between android and JRE guava-testlib modules

The file listing shows that files such as AbstractCollectionTester.java, AbstractContainerTester.java, AbstractMapTester.java, AbstractIteratorTester.java, AbstractTester.java, and many others are duplicated verbatim (or near-verbatim) between android/guava-testlib/src/ and the JRE guava-testlib/src/. This duplication is a maintenance burden: a bug fix or improvement in one copy must be manually applied to the other. Introducing a shared source-linking or symlink strategy (consistent with how Guava already manages android vs. JRE source sharing elsewhere in the repo) would eliminate this drift.

• [ ] Diff android/gu

Good first issues

1. Several test suite builder classes under android/guava-testlib/src/com/google/common/collect/testing/ (e.g., ConcurrentNavigableMapTestSuiteBuilder.java) have minimal Javadoc — adding package-level and class-level documentation would be a meaningful, low-risk contribution. 2) The DerivedCollectionGenerators.java file generates derived test data for collection tests but the derivation logic is undocumented — adding inline comments explaining each generator's purpose would help future contributors. 3) AbstractIteratorTester.java implements a state-machine iterator test but the state transition logic lacks ASCII diagram documentation — drawing and documenting the state machine would be a high-value addition.

Top contributors

• @cpovirk — 88 commits
• @java-team-github-bot — 3 commits
• @dependabot[bot] — 2 commits
• @holly-agyei — 2 commits
• @chaoren — 2 commits

Recent commits

• 93b09f0 — Remove obsolete Error Prone suppressions. (cpovirk)
• 8fa708b — Run more tests under J2KT/Native. (cpovirk)
• 73466ef — Add a few more nullness annotations, mostly from "On Leveraging Tests to Infer Nullable Annotations." (cpovirk)
• 43ad354 — Use some collection constructors (and a few more static imports). (cpovirk)
• 3240f46 — Automated Code Change (kluever)
• 36a579a — Static import methods from Types. (cpovirk)
• 4342259 — Bump the github-actions group with 3 updates (dependabot[bot])
• 0a32c33 — Adddress more warnings and review comments from https://github.com/google/guava/commit/f3113addf132b00523e786f105919a4c0 (cpovirk)
• e44e9b3 — Migrate escape tests from suites to individual tests. (cpovirk)
• 07ce1e9 — Hide APIs related to weighers and cache specs from J2KT. (cpovirk)

Security observations

The Google Guava repository demonstrates several positive security practices, including the use of OpenSSF Scorecard (evidenced by the scorecard workflow and badge), GPG signing for Maven Central releases, and SCM transparency. However, several medium and low severity

• Medium · Use of SNAPSHOT Version in Production BOM — android/guava-bom/pom.xml. The project BOM (Bill of Materials) declares version '999.0.0-HEAD-android-SNAPSHOT', which is a non-stable, mutable SNAPSHOT version. SNAPSHOT dependencies can change at any time without notice, potentially introducing untested or malicious code if the snapshot repository is compromised or if an attacker can publish to the snapshot repository. This affects supply chain integrity. Fix: Use pinned, stable release versions in production artifacts and BOMs. Avoid SNAPSHOT versions in released artifacts. Ensure snapshot repositories are secured and access-controlled.
• Medium · Dependency Version Pinning Not Verified — android/guava-bom/pom.xml, .mvn/wrapper/maven-wrapper.properties. The POM file references plugin versions (central-publishing-maven-plugin 0.10.0, maven-gpg-plugin 3.0.1) and dependency versions derived from project.version. Without checksum or signature verification enforced in the Maven build configuration, there is a risk of dependency substitution attacks. The .mvn/wrapper/maven-wrapper.properties file should also be verified to ensure the Maven wrapper download URL is pinned with a checksum. Fix: Enforce checksum verification for all dependencies using Maven Enforcer Plugin or Artifact Checksum verification. Verify the Maven wrapper properties include a SHA-256 checksum for the Maven distribution download. Use Sigstore or similar tooling for supply chain security.
• Medium · Potential Insecure SCM/Distribution URLs (HTTP vs HTTPS) — android/guava-bom/pom.xml. The POM file references an HTTP URL for the Apache License: 'http://www.apache.org/licenses/LICENSE-2.0.txt'. While this is a metadata field and not a functional dependency, the use of plain HTTP URLs in POM metadata can contribute to mixed-content or MITM risks in certain tooling environments that fetch and validate these resources. Fix: Replace all HTTP URLs with HTTPS equivalents, including license URLs and any distribution management URLs, to ensure transport security for all referenced resources.
• Low · Developer Contact Information Exposure — android/guava-bom/pom.xml. The POM file explicitly lists a developer's personal email address (cpovirk@google.com) as required by Sonatype. While this is a common Maven Central requirement, it constitutes a minor information disclosure that could be used for targeted phishing or social engineering attacks against maintainers. Fix: Consider using a team or role-based email address (e.g., guava-team@google.com) instead of a personal address in publicly distributed POM files to reduce individual targeting risk.
• Low · No SECURITY.md or Vulnerability Disclosure Policy Visible — Repository root. The partial file structure does not include a SECURITY.md file. While the repository has CONTRIBUTING.md and other governance files, the absence of a visible security disclosure policy may delay responsible reporting of vulnerabilities, increasing risk of public disclosure before patches are available. Fix: Add a SECURITY.md file to the repository root that outlines the vulnerability reporting process, supported versions, and expected response timelines, following GitHub's recommended security disclosure practices.
• Low · GitHub Actions Workflow Security Not Fully Assessable — .github/workflows/ci.yml, .github/workflows/scorecard.yml. The repository contains GitHub Actions workflow files (.github/workflows/ci.yml, .github/workflows/scorecard.yml). Without reviewing the full content, common risks include use of unpinned third-party actions (e.g., 'uses: actions/checkout@v3' instead of a commit SHA), excessive permissions granted to workflow tokens, or pull_request_target triggers that could allow untrusted code execution. The presence of scorecard.yml is a positive signal. Fix: Pin all third-party GitHub Actions to specific commit SHAs rather than mutable tags. Apply least-privilege permissions to GITHUB_TOKEN. Avoid pull_request_target triggers with checkout of untrusted code. Regularly audit workflows with tools like actionlint or OpenSSF Scorecard.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.