diff --git a/.github/DISCUSSION_TEMPLATE/issue-triage-compilation.yml b/.github/DISCUSSION_TEMPLATE/issue-triage-compilation.yml index ca75af1f06..5c50674039 100644 --- a/.github/DISCUSSION_TEMPLATE/issue-triage-compilation.yml +++ b/.github/DISCUSSION_TEMPLATE/issue-triage-compilation.yml @@ -1,3 +1,5 @@ +# Mirrored by .github/ISSUE_TEMPLATE/issue-triage-compilation.yml: keep the body: +# sections identical (dev_tools/bin/edg-check-issue-templates checks this). body: - type: textarea attributes: diff --git a/.github/DISCUSSION_TEMPLATE/issue-triage-general.yml b/.github/DISCUSSION_TEMPLATE/issue-triage-general.yml index eadb73f9f4..2157475df6 100644 --- a/.github/DISCUSSION_TEMPLATE/issue-triage-general.yml +++ b/.github/DISCUSSION_TEMPLATE/issue-triage-general.yml @@ -1,7 +1,10 @@ +# Mirrored by .github/ISSUE_TEMPLATE/issue-triage-general.yml: keep the body: +# sections identical, apart from links to the other form +# (dev_tools/bin/edg-check-issue-templates checks this). body: - type: markdown attributes: - value: Please use the [compilation issue triage](https://github.com/edgcpp/compiler/discussions/categories/compilation-issue-triage) for filing issues involving source code compilation (i.e., most issues). + value: Please use the [compilation issue triage](https://github.com/edgcpp/compiler/discussions/categories/issue-triage-compilation) for filing issues involving source code compilation (i.e., most issues). - type: textarea attributes: label: Issue Summary diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..1d94741cfd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +# The issue template chooser. Collaborators may still open a blank issue (e.g. +# for a task or feature); everyone else can report problems through the +# Discussions triage categories. +blank_issues_enabled: true +contact_links: + - name: Compilation issue triage (Discussions) + url: https://github.com/edgcpp/compiler/discussions/categories/issue-triage-compilation + about: Report a compilation problem for triage if you can't file issues directly. + - name: General issue triage (Discussions) + url: https://github.com/edgcpp/compiler/discussions/categories/issue-triage-general + about: Report any other problem for triage if you can't file issues directly. + - name: Questions (Discussions) + url: https://github.com/edgcpp/compiler/discussions/categories/q-a + about: Ask questions about using or contributing to the project. diff --git a/.github/ISSUE_TEMPLATE/issue-triage-compilation.yml b/.github/ISSUE_TEMPLATE/issue-triage-compilation.yml new file mode 100644 index 0000000000..88f9c5cb33 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/issue-triage-compilation.yml @@ -0,0 +1,118 @@ +# Mirrors .github/DISCUSSION_TEMPLATE/issue-triage-compilation.yml: keep the +# body: sections identical (dev_tools/bin/edg-check-issue-templates checks +# this). +name: Compilation issue +description: The front end mis-compiles, rejects, accepts, or crashes on source code (most issues). +type: Bug +body: + - type: textarea + attributes: + label: Issue Summary + description: Provide a high level description of what you believe is going wrong and how it is impacting you. + placeholder: In rare instances when using lambdas inside of class templates, the front end refuses to instantiate the template. This code compiles fine with GCC and Clang. I had to adapt the code to work around the issue, but I prefer the implementation strategy I am sharing in this report. + validations: + required: true + - type: textarea + attributes: + label: Reproducing Source Code + description: | + Provide the source code reproducing the issue. + + *Please*: + 1. Reduce the translation unit to the smallest possible reproducing case. + 2. Upload the source code file(s) as a: `.cpp`, `.zip`, or `.tar.gz`. + 3. DO NOT paste a large code block here (a small legally-unencumbered code block is okay in place of an upload). + + > [!TIP] + > If you would like to reduce the issue but do not know how, checkout the [cvise](https://github.com/marxin/cvise/) project as this is VERY helpful for automatic issue reduction. Additionally, in many cases AI agents can successfully create a reduced test case (that is similar enough to still reproduce the problem) in a fraction of the time. + + > [!IMPORTANT] + > If this source code is not compatible with the [project license](https://edgcpp.org/LICENSE.txt), please include a LICENSE.txt file or license disclosure comment at the start of all relevant files. + placeholder: | + [reproducer.zip](https://github.com/user-attachments/files/...) + validations: + required: true + - type: input + attributes: + label: Command-line Options + description: Provide the command-line options needed for reproducing the problem. + placeholder: cpfe --c++26 test.cpp + validations: + required: true + - type: dropdown + attributes: + label: Type of Issue + options: + - | + [Front End] This code *SHOULD* compile with these options. + - | + [Front End] This code *SHOULD NOT* compile with these options. + - | + [Front End] I do not care but this code *CRASHES* the compiler. + - | + [Back End] There is a problem with the generated C code. + - | + [Back End] There is a problem with the generated C++ code. + validations: + required: true + - type: textarea + attributes: + label: Additional Details + description: Provide any additional clarifying details that might help us better understand what is currently happening and what you expect to happen. + placeholder: The generated C code does not compile with gcc 14. + - type: dropdown + attributes: + label: Reproducing (Standard) Configuration(s) + description: | + What CMake preset-based configurations have you observed reproducing this issue (if any)? + + > [!NOTE] + > While you can select any configuration you know to reproduce the problem, you do not need to check every configuration. + multiple: true + options: + - macos-arm-clang-debug + - macos-arm-clang-release + - macos-x86-clang-debug + - macos-x86-clang-multi-thread-debug + - macos-x86-clang-release + - linux-clang-debug + - linux-clang-lsp + - linux-clang-release + - linux-clang-debuggable-release + - linux-gcc-debug + - linux-i686-gcc-debug + - linux-gcc-multi-thread-debug + - linux-gcc-multi-thread-release + - linux-gcc-release + - linux-gcc-debuggable-release + - linux-gcc-reflection-release + - windows-msvc-debug + - windows-msvc-release + - type: textarea + attributes: + label: Reproducing (Non-standard) Configuration + description: | + If this problem does not reproduce in one of the above "standard" configurations, please provide the output obtained when using the `--dump_configuration` command-line option with the EDG front end you are using. + + > [!TIP] + > Consider contributing a new build & testing configuration to increase coverage and make it easier to report (and reproduce) any future issues. + placeholder: | + [config.txt](https://github.com/user-attachments/files/...) + - type: checkboxes + attributes: + label: "I acknowledge that:" + options: + - label: I have checked open issues and existing discussions before filing this report. + required: true + - label: The reproducing source code that I have provided does not depend on headers that I have not included with my submission. + required: true + - label: I have reduced the reproducing source code to the best of my ability. + required: true + - label: I have selected at least one standard configuration or uploaded a non-standard configuration dump. + required: true + - label: I understand code shared via this form is NOT confidential. + required: true + - label: I have permission to share the reproducing source code and grant permission for the project to use the source code (or derivatives of the source code) to create tests. + required: true + - label: I agree that any tests created using the reproducing source code (or deriatives of it) will be licensed under [project license](https://edgcpp.org/LICENSE.txt) unless I included a `LICENSE.txt` file in my `.zip` or `.tar.gz` upload. If I included a `LICENSE.txt` file, any tests created using the reproducing source code will be governed by the terms of the license I provided instead. + required: true diff --git a/.github/ISSUE_TEMPLATE/issue-triage-general.yml b/.github/ISSUE_TEMPLATE/issue-triage-general.yml new file mode 100644 index 0000000000..7f7ea6519b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/issue-triage-general.yml @@ -0,0 +1,43 @@ +# Mirrors .github/DISCUSSION_TEMPLATE/issue-triage-general.yml: keep the body: +# sections identical, apart from links to the other form +# (dev_tools/bin/edg-check-issue-templates checks this). +name: General issue +description: Tooling, build, documentation, or other problems not involving compiling source code. +type: Bug +body: + - type: markdown + attributes: + value: Please use the [compilation issue triage](https://github.com/edgcpp/compiler/issues/new?template=issue-triage-compilation.yml) for filing issues involving source code compilation (i.e., most issues). + - type: textarea + attributes: + label: Issue Summary + description: Provide a high level description of what you believe is going wrong and how it is impacting you. + placeholder: | + `edg-docker-test` is printing the incorrect host path for some of the log files when run on MacOS Monterey. This is making it difficult for me to test my changes. + validations: + required: true + - type: textarea + attributes: + label: Observed Behavior + description: Please provide the behavior observed. + placeholder: When I run `edg-docker-test` I see the following log lines printed ... note how the second log is printed with its container path rather than a host path. + validations: + required: true + - type: textarea + attributes: + label: Expected Behavior + description: Please provide a description of how you would like things to work. + placeholder: All printed paths should be host paths. + validations: + required: true + - type: textarea + attributes: + label: Additional Details + description: Provide any additional details that you think may be helpful. + placeholder: I tried setting EDG_DOCKER_HOST_PATHS to 1 explicity and that did not help. However, setting EDG_DOCKER_HOST_PATHS to 2 does print the host and container path as expected. This makes me think the issue is specific to setting EDG_DOCKER_HOST_PATHS to 1. + - type: checkboxes + attributes: + label: "I acknowledge that:" + options: + - label: I have checked open issues and existing discussions before filing this report. + required: true diff --git a/.github/workflows/issue-templates.yml b/.github/workflows/issue-templates.yml new file mode 100644 index 0000000000..9c19aa9077 --- /dev/null +++ b/.github/workflows/issue-templates.yml @@ -0,0 +1,40 @@ +# Part of the EDG Compiler Project, under the Apache License v2.0 with LLVM +# Exceptions. +# See https://edgcpp.org/LICENSE.txt for license information. +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +# +# Check that the issue forms (.github/ISSUE_TEMPLATE) and the discussion forms +# (.github/DISCUSSION_TEMPLATE) they mirror haven't drifted apart. + +name: Issue Templates + +on: + push: + branches: + - main + paths: + - .github/ISSUE_TEMPLATE/** + - .github/DISCUSSION_TEMPLATE/** + - .github/workflows/issue-templates.yml + - dev_tools/bin/edg-check-issue-templates + pull_request: + paths: + - .github/ISSUE_TEMPLATE/** + - .github/DISCUSSION_TEMPLATE/** + - .github/workflows/issue-templates.yml + - dev_tools/bin/edg-check-issue-templates + +permissions: + contents: read + +jobs: + check: + name: check-issue-templates + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Check out repository + uses: actions/checkout@v7 + + - name: Compare issue and discussion forms + run: python3 dev_tools/bin/edg-check-issue-templates diff --git a/dev_tools/bin/edg-check-issue-templates b/dev_tools/bin/edg-check-issue-templates new file mode 100755 index 0000000000..6c729ecd34 --- /dev/null +++ b/dev_tools/bin/edg-check-issue-templates @@ -0,0 +1,132 @@ +#!/usr/bin/env python3 + +# Part of the EDG Compiler Project, under the Apache License v2.0 with LLVM +# Exceptions. +# See https://edgcpp.org/LICENSE.txt for license information. +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +'''Check that the issue forms and the discussion forms match. + +Every form in .github/DISCUSSION_TEMPLATE has a twin of the same name in +.github/ISSUE_TEMPLATE, so contributors who can file issues use the same form +as everyone else. GitHub can't share one file between the two (issue forms +need name/description keys discussion forms don't allow), so the two copies +are kept by hand and this checks that their body: sections are identical, +apart from links to the other forms (a discussion category in one, an issue +form in the other). +''' + +import argparse +import difflib +import re +import sys + +from pathlib import Path +from typing import List, Optional + +REPOSITORY_URL = 'https://github.com/edgcpp/compiler' + +# Links to another form, which differ between the twins by design. +FORM_LINK_PATTERNS = [ + re.compile(re.escape(REPOSITORY_URL) + + r'/discussions/categories/([A-Za-z0-9_-]+)'), + re.compile(re.escape(REPOSITORY_URL) + + r'/issues/new\?template=([A-Za-z0-9_-]+)\.yml'), +] + +# Files in ISSUE_TEMPLATE that aren't forms. +NON_FORMS = {'config.yml'} + +# Top-level keys an issue form requires before its body. +ISSUE_FORM_KEYS = ['name', 'description'] + + +def form_body(path: Path) -> Optional[List[str]]: + '''Return the lines from the body: key on, with form links normalized.''' + lines = path.read_text(encoding = 'utf-8').splitlines(keepends = True) + for index, line in enumerate(lines): + if line.startswith('body:'): + body = lines[index:] + for pattern in FORM_LINK_PATTERNS: + body = [pattern.sub(r'
', text) for text in body] + return body + return None + + +def missing_issue_form_keys(path: Path) -> List[str]: + '''Return the required top-level keys path lacks before its body.''' + header = [] + for line in path.read_text(encoding = 'utf-8').splitlines(): + if line.startswith('body:'): + break + header.append(line) + return [ + key for key in ISSUE_FORM_KEYS + if not any(line.startswith(key + ':') for line in header) + ] + + +def main() -> int: + parser = argparse.ArgumentParser(description = __doc__.splitlines()[0]) + parser.add_argument( + '--github-dir', + type = Path, + default = Path(__file__).resolve().parents[2] / '.github', + help = 'the .github directory to check (default: this repository\'s)' + ) + args = parser.parse_args() + + discussion_dir = args.github_dir / 'DISCUSSION_TEMPLATE' + issue_dir = args.github_dir / 'ISSUE_TEMPLATE' + discussion_forms = {path.name for path in discussion_dir.glob('*.yml')} + issue_forms = { + path.name for path in issue_dir.glob('*.yml') + if path.name not in NON_FORMS + } + + errors = 0 + for name in sorted(discussion_forms - issue_forms): + print(f"error: {discussion_dir / name} has no twin in {issue_dir}", + file = sys.stderr) + errors += 1 + for name in sorted(issue_forms - discussion_forms): + print(f"error: {issue_dir / name} has no twin in {discussion_dir}", + file = sys.stderr) + errors += 1 + + for name in sorted(discussion_forms & issue_forms): + discussion_form = discussion_dir / name + issue_form = issue_dir / name + missing = missing_issue_form_keys(issue_form) + if len(missing) != 0: + print(f"error: {issue_form} lacks the top-level key(s) " + f"{', '.join(missing)}", file = sys.stderr) + errors += 1 + discussion_body = form_body(discussion_form) + issue_body = form_body(issue_form) + if discussion_body is None or issue_body is None: + for path, body in ((discussion_form, discussion_body), + (issue_form, issue_body)): + if body is None: + print(f"error: {path} has no body: key", file = sys.stderr) + errors += 1 + continue + if discussion_body != issue_body: + print(f"error: the body: sections of {discussion_form} and " + f"{issue_form} differ:", file = sys.stderr) + sys.stderr.writelines(difflib.unified_diff( + discussion_body, + issue_body, + fromfile = str(discussion_form), + tofile = str(issue_form) + )) + errors += 1 + + if errors != 0: + return 1 + print(f"{len(discussion_forms & issue_forms)} form(s) match.") + return 0 + + +if __name__ == '__main__': + sys.exit(main())