* 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.
The goal is not to *own* a decision, but to *share* it with other teams, and improve the build tool together.

Should and should not do's.

## Error messages and suggestions

Traditionally, if an error occurred, the error message and the possible solution were provided to the console via a single String in the corresponding exception.
That meant possible solutions for Problems could be scattered all over the console output.
To improve the user experience, we introduced a new way to provide suggestions.

Java serialization is one way to implement this, however, despite its simplicity of implementation, it has several drawbacks:

- **Performance:**
Java's built-in serialization mechanism is often slower compared to other serialization solutions.
This is due to Java's use of reflection and the need to maintain a lot of metadata.

- **Size of Serialized Data:**

            }

            if (!references.isEmpty()) {
                slf4jLogger.error("");
                slf4jLogger.error("For more information about the errors and possible solutions"
                        + ", please read the following articles:");

                for (Map.Entry<String, String> entry : references.entrySet()) {

        o -> o.orElse(null), Comparator.nullsLast(valueComparator));
  }

  /**
   * Returns the minimum of the two values. If the values compare as 0, the first is returned.
   *
   * <p>The recommended solution for finding the {@code minimum} of some values depends on the type
   * of your data and the number of elements you have. Read more in the Guava User Guide article on

    return least(k, comparator.reversed());
  }

  /**
   * Returns the minimum of the two values. If the values compare as 0, the first is returned.
   *
   * <p>The recommended solution for finding the {@code minimum} of some values depends on the type
   * of your data and the number of elements you have. Read more in the Guava User Guide article on

    id: context
    attributes:
      label: Context (optional)
      description: |
        How has this issue affected you? What are you trying to accomplish?
        Providing context helps us come up with a solution that is most useful in the real world
    validations:
      required: false
  - type: input
    id: page
    attributes:
      label: Page with the problem

    id: context
    attributes:
      label: Context (optional)
      description: |
        How has this issue affected you? What are you trying to accomplish?
        Providing context helps us come up with a solution that is most useful in the real world
    validations:
      required: false
  - type: textarea
    id: steps-to-reproduce
    attributes:
      label: Steps to Reproduce
      description: |

    }

    processResources {
        // Add generated sources to the main jar because `src` or any other Gradle distribution does not include them.
        // A more general solution is probably required: https://github.com/gradle/gradle/issues/21114
        from(apiExtensionsFileCollection)
    }

// -- Version manifest properties --------------------------------------

    id: context
    attributes:
      label: Context (optional)
      description: |
        How has this issue affected you? What are you trying to accomplish?
        Providing context helps us come up with a solution that is most useful in the real world
    validations:
      required: false
  - type: textarea
    id: steps-to-reproduce
    attributes:
      label: Steps to Reproduce
      description: |