How to contribute
=================

Thank you so much for wanting to contribute to Guava! Here are a few important
things you should know about contributing:

1.  API changes require discussion, use cases, etc. Code comes later.
2.  Pull requests are great for small fixes for bugs, documentation, etc.
3.  Pull requests are not merged directly into the master branch.
4.  Code contributions require signing a Google CLA.

API changes
-----------

 *       under all environments. We could fight this by fully qualifying the annotation, but the
 *       result will be verbose and attention-grabbing.
 *   <li>We need to be careful about how we suppress {@code suite()} methods in {@code common.io}.
 *       The generated suite for {@code FooTest} ends up containing {@code FooTest} itself plus some

  //    Imagine:
  //    guard.lock();
  //    try { /* monitor locked and guard satisfied here */ }
  //    finally { guard.unlock(); }
  // Here are Justin's design notes about this:
  //
  // This idea has come up from time to time, and I think one of my
  // earlier versions of Monitor even did something like this. I ended
  // up strongly favoring the current interface.
  //

     * hopefully could avoid implementing Entry or ValueSetLink at all. (But note that that approach
     * requires us to define extra classes -- unfortunate under Android.) *Then* we could consider
     * lying about the fields below on the grounds that we always initialize them just after the
     * constructor -- an example of the kind of lying that our hypothetical bytecode rewriter would

                   */
                  Set<Integer> unused = graph.successors(first);
                  return null;
                }
              }));
    }

    // For more about this test, see the equivalent in AbstractNetworkTest.
    for (Future<?> future : futures.build()) {
      future.get();
    }
    executor.shutdown();
  }

     * inputs, rather than as if it never tolerates them.
     *
     * We rely on checkers to implement special cases to catch dangerous calls to join(), etc. based
     * on what they know about the particular Joiner instances the calls are performed on.
     *
     * (In addition to useForNull, we also offer skipNulls. It, too, tolerates null inputs, but its

 *   <li>The documentation style for testcases is to provide as javadoc a simple sentence or two
 *       describing the property that the testcase method purports to test. The javadocs do not say
 *       anything about how the property is tested. To find out, read the code.
 *   <li>These tests are "conformance tests", and do not attempt to test throughput, latency,

      for (LockGraphNode acquiredLock : acquiredLocks) {
        checkAcquiredLock(policy, acquiredLock);
      }
    }

    /**
     * Checks the acquisition-ordering between {@code this}, which is about to be acquired, and the
     * specified {@code acquiredLock}.
     *
     * <p>When this method returns, the {@code acquiredLock} should be in either the {@code

     */
    /*
     * TODO(cpovirk): use Object[] instead of E[] in the mainline? (The backport is different and
     * doesn't need this suppression, but we keep it to minimize diffs.) Generally be more clear
     * about when we have an Object[] vs. a Comparable[] or other array type in internalArray? If we
     * used Object[], we might be able to optimize toArray() to use clone() sometimes. (See
     * cl/592273615 and cl/592273683.)
     */

      Multiset<?> multisetToModify, Multiset<?> multisetToRetain) {
    return retainOccurrencesImpl(multisetToModify, multisetToRetain);
  }

  /** Delegate implementation which cares about the element type. */
  private static <E extends @Nullable Object> boolean retainOccurrencesImpl(
      Multiset<E> multisetToModify, Multiset<?> occurrencesToRetain) {
    checkNotNull(multisetToModify);