Skip to content

chore: improve GitHub issue templates with structured forms #528

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aureliolo merged 4 commits into from
Mar 17, 2026
Merged

chore: improve GitHub issue templates with structured forms #528

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e51de91
chore: improve GitHub issue templates with structured forms
Aureliolo Mar 17, 2026
3d1afec
fix: address PR review findings for issue templates
Aureliolo Mar 17, 2026
90bb5af
fix: remove non-existent install methods from bug report template
Aureliolo Mar 17, 2026
e9377e5
fix: improve doctor output field with fallback guidance and example
Aureliolo Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
name: Bug Report
description: Report a bug, crash, or unexpected behavior
title: "[Bug] "
labels:
- type:bug
body:
- type: markdown
attributes:
value: |
Thanks for reporting a bug. Please fill in as much detail as you can — it helps us fix things faster.

- type: dropdown
id: component
attributes:
label: Component
description: Which part of SynthOrg is affected?
options:
- Backend (Python API / engine)
- Dashboard (Vue web UI)
- CLI (Go binary / installer)
- Docker (compose / containers)
- Docs
validations:
required: true
Comment on lines +12 to +24

@gemini-code-assist gemini-code-assist Bot Mar 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The removed installer-failure.yml template had a helpful install-method dropdown. This information is lost in the new unified bug report, which is a regression for debugging installation issues. While conditional fields aren't supported in GitHub Issue forms, you could add this back as an optional dropdown to gather this crucial information for CLI/installer-related bugs.

I'd suggest adding the following block after this component dropdown:

  - type: dropdown
    id: install-method
    attributes:
      label: Installation method (if applicable)
      description: If this bug is about the CLI/installer, how did you install it?
      options:
        - Homebrew (brew install)
        - Scoop (scoop install)
        - curl | sh (Linux/macOS)
        - PowerShell installer (Windows)
        - Manual download from GitHub Releases
        - Built from source (go build)
    validations:
      required: false


- type: dropdown
id: severity
attributes:
label: Severity
options:
- Crash / data loss
- Wrong behavior (feature broken)
- Performance issue
- Cosmetic / minor
validations:
required: true

- type: dropdown
id: os
attributes:
label: Operating system
options:
- macOS (Apple Silicon / arm64)
- macOS (Intel / amd64)
- Linux (amd64)
- Linux (arm64)
- Windows (amd64)
- Windows (arm64)
validations:
required: true
Comment on lines +12 to +64

@coderabbitai coderabbitai Bot Mar 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Installer triage requirements are under-specified in this unified bug form.

Line [20] includes “CLI (Go binary / installer)”, but there is no required installation method field and no dedicated CLI-installation template path. This regresses the linked requirement for installer-specific intake and makes install failures harder to classify.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/ISSUE_TEMPLATE/bug_report.yml around lines 12 - 50, The unified bug
form lacks an installer-specific intake for the CLI component: add a required
dropdown field with id: installation_method (options like package manager,
installer script, binary download, Docker image, other) and
validations.required: true, and update the routing/metadata so when id:
component selects "CLI (Go binary / installer)" the issue is directed to or
loads a dedicated CLI-installer template/path for further installer triage;
reference the existing fields id: component, id: severity and id: os when adding
the new installation_method field and ensure the new field appears near line
where id: component is defined so installer info is captured before submission.


- type: textarea
id: description
attributes:
label: What happened?
description: Describe what you expected and what actually happened.
validations:
required: true

- type: textarea
id: steps
attributes:
label: Steps to reproduce
placeholder: |
1. Run `synthorg start`
2. Open http://localhost:3000
3. Click on ...
4. See error
validations:
required: true

- type: textarea
id: error
attributes:
label: Error output / logs
description: Full error message, stack trace, or relevant log output.
render: shell
validations:
required: false

- type: textarea
id: version
attributes:
label: Version info
description: "Output of `synthorg version`, or the version you tried to install."
placeholder: |
synthorg v0.3.0
commit: abc1234
built: 2026-03-15T12:00:00Z
render: shell
validations:
required: false

@gemini-code-assist gemini-code-assist Bot Mar 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The version field is crucial for debugging, but it's currently optional. This can lead to incomplete bug reports that are difficult to reproduce. Please consider making this field required to ensure you always get the version information. Users who have installation failures can specify the version they were attempting to install.

      required: true


- type: textarea
id: doctor
attributes:
label: Doctor output
description: |
If SynthOrg is installed, paste the output of `synthorg doctor`.
This collects OS, architecture, Docker version, container status, health checks,
and config (secrets are redacted). It makes debugging much faster.
placeholder: |
Paste `synthorg doctor` output here (optional but very helpful)
render: json
validations:
required: false

Comment on lines +95 to +129

@coderabbitai coderabbitai Bot Mar 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

version and doctor should be required-with-fallback, not optional.

Per the linked objective, reporters should provide version and doctor diagnostics (or explicitly state “not installed”). Current optional fields at Line [81] and Line [94] will lead to low-signal bug reports.

Suggested patch 
   - type: textarea
     id: version
@@
     validations:
-      required: false
+      required: true

   - type: textarea
     id: doctor
     attributes:
       label: Doctor output
       description: |
-        If SynthOrg is installed, paste the output of `synthorg doctor`.
+        Paste output of `synthorg doctor`.
+        If not installed yet, write: `not installed`.
         This collects OS, architecture, Docker version, container status, health checks,
         and config (secrets are redacted). It makes debugging much faster.
       placeholder: |
-        Paste `synthorg doctor` output here (optional but very helpful)
+        {
+          "os": "linux",
+          "arch": "amd64",
+          "docker": "24.x",
+          "status": "healthy"
+        }
+        # or: not installed
       render: json
     validations:
-      required: false
+      required: true
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/ISSUE_TEMPLATE/bug_report.yml around lines 81 - 107, Make the
version and doctor blocks (ids "version" and "doctor") required-with-fallback by
changing validations.required from false to true and adding an explicit
installation-status selector (e.g., new field id "installation_status" with
options "installed" and "not_installed"); enforce conditional validation so
"version" and "doctor" are required only when installation_status == "installed"
and allowed to be empty when "not_installed", and update their placeholders to
instruct users to pick "Not installed" if SynthOrg isn't present.

- type: textarea
id: context
attributes:
label: Additional context
description: "Screenshots, workarounds tried, related issues, etc."
validations:
required: false
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Documentation
url: https://synthorg.io/docs/
about: Check the docs before opening an issue
- name: Discussions
url: https://github.com/Aureliolo/synthorg/discussions
about: Ask questions or share ideas
- name: Security Vulnerabilities
url: https://github.com/Aureliolo/synthorg/security/policy
about: Report security vulnerabilities privately
56 changes: 56 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
name: Feature Request
description: Suggest a new feature or enhancement
title: "[Feature] "
labels:
- type:feature
body:
- type: markdown
attributes:
value: |
Thanks for suggesting a feature. Describe what you'd like and why it matters.

- type: dropdown
id: component
attributes:
label: Component
description: Which part of SynthOrg does this affect?
options:
- Backend (Python API / engine)
- Dashboard (Vue web UI)
- CLI (Go binary)
- Docker (compose / containers)
- Docs
validations:
required: true

- type: textarea
id: description
attributes:
label: Description
description: What do you want and what problem does it solve?
validations:
required: true

- type: textarea
id: motivation
attributes:
label: Motivation
description: Why is this needed? What's the current workaround (if any)?
validations:
required: false

@gemini-code-assist gemini-code-assist Bot Mar 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The motivation field is key to understanding the value of a feature request. Making it optional might lead to suggestions without a clear purpose or problem statement. To improve the quality of feature requests, please consider making this field required.

      required: true


- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Other approaches you thought of and why this one is better.
validations:
required: false

- type: textarea
id: context
attributes:
label: Additional context
description: "Mockups, links, research, related issues, etc."
validations:
required: false
Comment on lines +12 to +75

@coderabbitai coderabbitai Bot Mar 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Missing required product-intake fields from the linked objective.

From Line [12] onward, the form omits: (1) design spec reference, (2) dependency/related-issues field, and (3) scope self-assessment. That reduces triage quality and does not fully meet issue #522 acceptance criteria.

Suggested patch 
   - type: textarea
     id: alternatives
@@
     validations:
       required: false

+  - type: input
+    id: design_spec
+    attributes:
+      label: Design spec / RFC reference
+      description: Link to spec, RFC, mock, or proposal (if available).
+      placeholder: https://...
+    validations:
+      required: false
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies / related issues
+      description: Related issues, blockers, or upstream dependencies.
+      placeholder: "#123, `#456`, depends on ..."
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope self-assessment
+      options:
+        - Small (localized change)
+        - Medium (cross-component changes)
+        - Large (architecture/major workflow impact)
+    validations:
+      required: true
+
   - type: textarea
     id: context
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- type: dropdown
id: component
attributes:
label: Component
description: Which part of SynthOrg does this affect?
options:
- Backend (Python API / engine)
- Dashboard (Vue web UI)
- CLI (Go binary)
- Docker (compose / containers)
- Docs
validations:
required: true
- type: textarea
id: description
attributes:
label: Description
description: What do you want and what problem does it solve?
validations:
required: true
- type: textarea
id: motivation
attributes:
label: Motivation
description: Why is this needed? What's the current workaround (if any)?
validations:
required: false
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Other approaches you thought of and why this one is better.
validations:
required: false
- type: textarea
id: context
attributes:
label: Additional context
description: "Mockups, links, research, related issues, etc."
validations:
required: false
- type: dropdown
id: component
attributes:
label: Component
description: Which part of SynthOrg does this affect?
options:
- Backend (Python API / engine)
- Dashboard (Vue web UI)
- CLI (Go binary)
- Docker (compose / containers)
- Docs
validations:
required: true
- type: textarea
id: description
attributes:
label: Description
description: What do you want and what problem does it solve?
validations:
required: true
- type: textarea
id: motivation
attributes:
label: Motivation
description: Why is this needed? What's the current workaround (if any)?
validations:
required: false
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Other approaches you thought of and why this one is better.
validations:
required: false
- type: input
id: design_spec
attributes:
label: Design spec / RFC reference
description: Link to spec, RFC, mock, or proposal (if available).
placeholder: https://...
validations:
required: false
- type: textarea
id: dependencies
attributes:
label: Dependencies / related issues
description: Related issues, blockers, or upstream dependencies.
placeholder: "#123, `#456`, depends on ..."
validations:
required: false
- type: dropdown
id: scope
attributes:
label: Scope self-assessment
options:
- Small (localized change)
- Medium (cross-component changes)
- Large (architecture/major workflow impact)
validations:
required: true
- type: textarea
id: context
attributes:
label: Additional context
description: "Mockups, links, research, related issues, etc."
validations:
required: false
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/ISSUE_TEMPLATE/feature_request.yml around lines 12 - 56, The feature
request template is missing required intake fields referenced by the objective:
add three new form blocks with unique ids design_spec, dependencies, and
scope_assessment (similar to existing blocks like component, description,
motivation) so triage captures design spec reference, related/dependency issues,
and a scope self-assessment; each block should include an attributes.label and
attributes.description and set validations.required: true (or required:false for
dependencies if you prefer optional linking), and place them after the existing
description/component sections to satisfy issue `#522` acceptance criteria.

79 changes: 0 additions & 79 deletions .github/ISSUE_TEMPLATE/installer-failure.yml
View file
Open in desktop

This file was deleted.

Loading