Add Contributor Issue Templates

.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:

.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

.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.

.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

.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

.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

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'<form \1>', 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())