We use *Specification* and *Discovery* documents stored in Google Drive, but they present some downsides:

* They are rarely updated after creation and initial review, and then become hard to follow, especially after important decisions are made
* They are not synced with the code to reflect the eventual solution that is committed
* Google Docs is not a "code-oriented" tool, like asciidoc can be

### Security vulnerabilities

Do not report security vulnerabilities to the public issue tracker. Follow our [Security Vulnerability Disclosure Policy](https://github.com/gradle/gradle/security/policy).

### Follow the Code of Conduct

Contributors must follow the Code of Conduct outlined at [https://gradle.org/conduct/](https://gradle.org/conduct/).

### Additional help

name: Bug Report
description: Create a report to help us improve
labels: [ "a:bug", "to-triage" ]
assignees: [ ]
body:
  - type: markdown
    attributes:
      value: |
        Please follow the instructions below.
        We receive dozens of issues every week, so to stay productive, we will close issues that don't provide enough information.

      - {{ not (is_docs_only_change) }}
      - {{ not (is_formatting_only_change) }}
    run:
      - action: add-label@v1
        args:
          label: "⚠️ Lacks Tests"
          color: {{ colors.yellow }}
      - action: add-comment@v1
        args:
          comment: |
            :warning: This PR appears to be lacking tests.  Consider adding tests to cover the new functionality.

- [ ] Check ["Allow edit from maintainers" option](https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/) in pull request so that additional changes can be pushed by Gradle team.

        TaskProvider<Sync> userguideFlattenSources = tasks.register("stageUserguideSource", Sync.class, task -> {
            task.setDuplicatesStrategy(DuplicatesStrategy.FAIL);

            // TODO: This doesn't allow adoc files to be generated?
            task.from(extension.getUserManual().getRoot(), sub -> {
                sub.include("**/*.adoc");
                // Flatten adocs into a single directory

            // https://www.jetbrains.com/help/teamcity/shared-resources.html#Viewing+Shared+Resources+Usage
            // https://blog.jetbrains.com/teamcity/2013/05/explaining-the-shared-resources-plugin/
            // we only allow 1 promotion job running at the same time to avoid website xml conflicts
            feature {
                type = "JetBrains.SharedResources"
                param("locks-param", "WebsiteReleasesXml writeLock")
            }

      - {{ source.diff.files | matchDiffLines(regex=r/(TODO)|(todo)/) | some }}
    run:
      - action: add-label@v1
        args:
          label: "⚠️ Includes TODOs"
          color: {{ colors.yellow }}
      - action: add-comment@v1
        args:
          comment: |
            :warning: 'There are new TODOs present in this change.  Should any be removed?'

      - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
    run:
      - action: add-label@v1
        args:
          label: "⚠️ Missing Javadoc"
          color: {{ colors.yellow }}
      - action: add-comment@v1
        args:
          comment: |
            :warning: This PR creates new top-level Java classes, but has no Javadoc present. Please document all top-level classes with Javadoc.

is: