updated doc+fixing code issues

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,70 +1,120 @@
 name: Bug report
-description: Report a reproducible problem
-title: "[Bug]: "
+description: Report reproducible incorrect or regressed behavior
 labels:
   - bug
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for reporting a bug. Please include enough detail to reproduce it.
+        Thanks for reporting a problem.
+
+        Do not report security vulnerabilities here. Follow `SECURITY.md` and use private vulnerability reporting.
+
+  - type: dropdown
+    id: problem_type
+    attributes:
+      label: Problem type
+      description: Select the option that best describes the problem.
+      options:
+        - Bug
+        - Regression
+        - Not sure
+    validations:
+      required: true
+
   - type: textarea
     id: summary
     attributes:
       label: Summary
-      description: What is wrong?
-      placeholder: Clear and short description of the bug.
+      description: Describe the incorrect behavior and its impact.
+      placeholder: A clear and concise description of the problem.
+    validations:
+      required: true
+
+  - type: input
+    id: package_version
+    attributes:
+      label: Affected package version
+      placeholder: e.g. 2.4.1 or dev-main@abc1234
     validations:
       required: true
+
+  - type: input
+    id: last_known_working
+    attributes:
+      label: Last known working version or commit
+      description: Complete this when reporting a regression, if known.
+      placeholder: e.g. 2.4.0 or abc1234
+
+  - type: input
+    id: first_known_broken
+    attributes:
+      label: First known broken version or commit
+      description: Complete this when known.
+      placeholder: e.g. 2.4.1 or def5678
+
   - type: textarea
     id: reproduce
     attributes:
-      label: Steps to reproduce
-      description: Share exact commands, config, and steps.
+      label: Minimal reproduction
+      description: Provide the smallest code sample, command, configuration or repository that reproduces the problem.
       placeholder: |
-        1. Run `composer ic:tests`
-        2. ...
+        1. Install or configure ...
+        2. Run ...
         3. Observe ...
     validations:
       required: true
+
   - type: textarea
     id: expected
     attributes:
       label: Expected behavior
-      placeholder: What did you expect to happen?
+      placeholder: Describe what should happen.
     validations:
       required: true
+
   - type: textarea
     id: actual
     attributes:
       label: Actual behavior
-      placeholder: What happened instead? Include full error output if possible.
+      placeholder: Describe what happens instead.
     validations:
       required: true
+
+  - type: textarea
+    id: error_output
+    attributes:
+      label: Relevant output or errors
+      description: Include only the relevant, sanitized output.
+      render: shell
+
   - type: input
     id: php_version
     attributes:
       label: PHP version
-      placeholder: "e.g. 8.3.8"
+      placeholder: e.g. 8.4.13
     validations:
       required: true
+
   - type: input
     id: composer_version
     attributes:
       label: Composer version
-      placeholder: "e.g. 2.9.2"
+      placeholder: e.g. 2.9.2
     validations:
       required: true
+
   - type: textarea
     id: environment
     attributes:
-      label: Environment details
-      description: OS, CI provider, shell, and anything else relevant.
-      placeholder: Ubuntu 24.04, GitHub Actions, bash...
+      label: Environment
+      description: Include the operating system, relevant extensions, dependency mode, runtime and CI provider when applicable.
+      placeholder: Ubuntu 24.04, locked dependencies, ext-json enabled, GitHub Actions...
     validations:
       required: true
+
   - type: textarea
     id: additional
     attributes:
       label: Additional context
-      description: Links, screenshots, logs, or related issues.
+      description: Add related issues, screenshots, logs, workarounds or other useful context.

.github/ISSUE_TEMPLATE/ci_failure.yml

@@ -1,48 +1,101 @@
 name: CI failure
-description: Report a reproducible CI or workflow failure
-title: "[CI]: "
+description: Report a reproducible PHPForge or workflow failure
 labels:
   - ci
 body:
   - type: markdown
     attributes:
       value: |
-        Use this form when CI fails unexpectedly and can be reproduced.
+        Use this form when a CI workflow or PHPForge check fails unexpectedly.
+
+        Do not report security vulnerabilities here. Follow `SECURITY.md` and use private vulnerability reporting.
+
   - type: input
     id: workflow
     attributes:
-      label: Workflow/job name
-      placeholder: security-standards / phpforge
+      label: Workflow and job
+      placeholder: e.g. CI / PHP 8.4
     validations:
       required: true
+
   - type: input
     id: run_url
     attributes:
       label: Failing run URL
+      description: Provide a link when the run is accessible.
       placeholder: https://github.com/OWNER/REPOSITORY/actions/runs/...
-    validations:
-      required: true
+
   - type: textarea
-    id: command
+    id: failing_step
     attributes:
-      label: Failing command
-      description: Exact command or step that failed.
+      label: Failing step or command
+      description: Include the exact workflow step or command that failed.
       placeholder: composer ic:ci
+      render: shell
     validations:
       required: true
+
   - type: textarea
     id: logs
     attributes:
-      label: Error output
-      description: Paste the relevant error section.
+      label: Relevant error output
+      description: Paste the smallest useful, sanitized error section.
       render: shell
     validations:
       required: true
-  - type: textarea
-    id: local_check
+
+  - type: dropdown
+    id: local_result
     attributes:
       label: Local reproduction
-      description: Can you reproduce locally? If yes, include steps.
-      placeholder: Yes/No + details
+      description: Does the same failure occur when running the relevant command locally?
+      options:
+        - Yes
+        - No
+        - Not attempted
+    validations:
+      required: true
+
+  - type: textarea
+    id: local_details
+    attributes:
+      label: Local reproduction details
+      description: Include the command, result and any differences from CI.
+      placeholder: composer ic:ci fails locally with the same error...
+
+  - type: input
+    id: php_version
+    attributes:
+      label: PHP version
+      placeholder: e.g. 8.4.13
+    validations:
+      required: true
+
+  - type: input
+    id: composer_version
+    attributes:
+      label: Composer version
+      placeholder: e.g. 2.9.2
     validations:
       required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Runner and dependency environment
+      description: Include the runner OS, dependency mode, relevant extensions, matrix values and PHPForge version when known.
+      placeholder: ubuntu-latest, prefer-lowest, PHPForge 1.x, ext-json enabled...
+    validations:
+      required: true
+
+  - type: textarea
+    id: recent_changes
+    attributes:
+      label: Relevant recent changes
+      description: Mention dependency, configuration, workflow or source changes that may be related.
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add related issues, screenshots, logs or other useful context.

.github/ISSUE_TEMPLATE/docs_improvement.yml

@@ -1,34 +1,58 @@
-name: Docs improvement
-description: Report missing, unclear, or incorrect documentation
-title: "[Docs]: "
+name: Documentation improvement
+description: Report missing, outdated, unclear or incorrect documentation
 labels:
   - documentation
 body:
-  - type: textarea
+  - type: dropdown
+    id: problem_type
+    attributes:
+      label: Documentation problem
+      options:
+        - Incorrect
+        - Outdated
+        - Missing
+        - Unclear
+        - Example needed
+        - Other
+    validations:
+      required: true
+
+  - type: input
     id: location
     attributes:
       label: Documentation location
-      description: File path or URL.
-      placeholder: README.md section "Quick Start"
+      description: Provide the file path, section, symbol or URL.
+      placeholder: README.md — Quick Start
     validations:
       required: true
+
   - type: textarea
-    id: issue
+    id: problem
     attributes:
-      label: What is unclear or incorrect?
-      placeholder: This section says...
+      label: Problem
+      description: Explain what is missing, unclear, outdated or incorrect.
+      placeholder: The current documentation says or omits...
     validations:
       required: true
+
   - type: textarea
-    id: suggestion
+    id: expected
     attributes:
-      label: Suggested improvement
-      description: Propose revised wording, structure, or examples.
-      placeholder: It would be clearer if...
+      label: Expected documentation
+      description: Describe what readers should be able to understand or accomplish.
+      placeholder: Readers should be able to...
     validations:
       required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested improvement
+      description: Optionally propose wording, structure, examples or references.
+      placeholder: It may be clearer to...
+
   - type: textarea
     id: additional
     attributes:
       label: Additional context
-      description: Related links, screenshots, or prior discussions.
+      description: Add related links, screenshots, discussions or examples.