# Contributing to the Gradle Build Tool

Thank you for your interest in contributing to Gradle!
This guide explains how to contribute to the core Gradle components, 
extensions and documentation located in this repository.
For other extensions and components, see the 
[Gradle Community Resources](https://gradle.org/resources/).

This guide will help you to...

* maximize the chance of your changes being accepted
* work on the Gradle code base

translations, separated by a colon (:). Use these translations, do not use your own. If an existing translation does not use these terms, update it to use them. In the below list, a term or a translation may be followed by an explanation in brackets, which explains when to translate the term this way. If a translation is preceded by `NOT`, then that means: do NOT use this translation for this term. English nouns, starting with the word `the`, have the German genus – `der`, `die`, `das` – prepended to their...

		Apply trims and rewrites to source file paths.
*/
package main

/*
Implementation details.

Cgo provides a way for Go programs to call C code linked into the same
address space. This comment explains the operation of cgo.

Cgo reads a set of Go source files and looks for statements saying
import "C". If the import has a doc comment, that comment is
taken as literal C code to be used as a preamble to any C code

  @Override
  @SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
  public int compare(Comparable<?> left, Comparable<?> right) {
    checkNotNull(left); // for GWT
    checkNotNull(right);
    return ((Comparable<Object>) left).compareTo(right);
  }

  @Override
  @SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
  public <S extends Comparable<?>> Ordering<@Nullable S> nullsFirst() {

/// tip

For new code and whenever possible, use `Annotated` as explained above. There are multiple advantages (explained below) and no disadvantages. 🍰

///

  @Override
  @SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
  public int compare(Comparable<?> left, Comparable<?> right) {
    checkNotNull(left); // for GWT
    checkNotNull(right);
    return ((Comparable<Object>) left).compareTo(right);
  }

  @Override
  @SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
  public <S extends Comparable<?>> Ordering<@Nullable S> nullsFirst() {

## What we expect from contributors

1. **Understand the content you submit, PRs as well as issues, and be able to explain it.** Our goal is for humans to use AI tools intentionally and with full control, rather than merely serving as proxies for AI agents. If you cannot explain the reason for something, we will assume you do not understand it, and the PR or issue will likely be closed.

    * You can start with [Python Types Intro](https://fastapi.tiangolo.com/python-types/), it explains what changes between different Python versions, in Python 3.9 and in Python 3.10.

   *
   * <p><b>Java 8+ users:</b> use {@link Comparator#naturalOrder} instead.
   */
  @SuppressWarnings({"unchecked", "rawtypes"})
  // TODO(kevinb): right way to explain this??
  // plus https://github.com/google/guava/issues/989
  public static <C extends Comparable> Ordering<C> natural() {
    return (Ordering<C>) NaturalOrdering.INSTANCE;
  }

  // Static factories

* To provide best practices and solutions we (as the *build tool* team) want to promote.
* To avoid asking the same thing multiple times during code review.
* To explain *rejected solutions*, for now, and future development, in case they are proposed again.

ADRs can be written by any team.
Like code, they should be reviewed by any other relevant teams.