name: Incompatible Change
description: Use this template to track the rollout of an incompatible change in Bazel
title: '[Incompatible Flag] OR [Incompatible Change Title]'
labels: ["untriaged", "incompatible-change"]
assignees:
  - sgowroji
  - iancha1992
  - satyanandak
body:
  - type: markdown
    attributes:
      value: >
        **Attention:**
        Please read https://bazel.build/release/backward-compatibility
        and https://bazel.build/contribute/breaking-changes for best practices of rolling out
        incompatible changes in Bazel.

  - type: textarea
    id: motivation
    attributes:
      label: Motivation
      description: Describe the motivation behind this change. Why is this change needed? What problem does it solve?
    validations:
      required: true

  - type: textarea
    id: description
    attributes:
      label: Description
      description: Provide a clear and concise description of the incompatible change. Explain what the incompatible change is and what impact it will have.
    validations:
      required: true

  - type: input
    id: incompatible_flag
    attributes:
      label: Incompatible Flag
      description: The incompatible flag used to guard this change. If no incompatible flag is used, briefly explain why (e.g. minor incompatible change that's trivial to migrate for).
    validations:
      required: true

  - type: textarea
    id: migration
    attributes:
      label: Migration Guide
      description: Provide guidance on how users can migrate to the new behavior. Include examples, code snippets, or links to relevant documentation.
    validations:
      required: true

  - type: dropdown
    id: bazel_version
    attributes:
      label: In which Bazel LTS version will this incompatible change be enabled?
      multiple: false
      options:
        - Bazel 8
        - Bazel 9
        - Bazel 10

  - type: textarea
    id: additional_context
    attributes:
      label: Additional Context
      description: Add any other context about the incompatible change here.

  - type: textarea
    id: todo_list
    attributes:
      label: TODO List
      description: >
        Choose a todo list based on whether incompatible flag is used, feel free to edit based on your needs.


        With incompatible flag (highly recommend for incompatible changes having large impact):

        \- \[ \] Implement the incompatible change at Bazel HEAD and guard it behind a flag.

        \- \[ \] Backport the incompatible flag to the latest LTS release.

        \- \[ \] Test the incompatible change with [downstream projects](https://github.com/bazelbuild/continuous-integration/blob/master/docs/downstream-testing.md#bazel-downstream-testing) and inform broken projects.

        \- \[ \] Flip the incompatible flag at Bazel HEAD.

        \- \[ \] Delete the incompatible flag and the old behavior at Bazel HEAD.


        Without incompatible flag (good for minor incompatible changes that are trivial to migrate for):

        \- \[ \] Implement the incompatible change at Bazel HEAD.

        \- \[ \] Check the [downstream pipeline](https://github.com/bazelbuild/continuous-integration/blob/master/docs/downstream-testing.md#bazel-downstream-testing) result and inform broken projects.