From 1daee9d9696c987a52bd446112ca7bec757dfa08 Mon Sep 17 00:00:00 2001
From: jyviko <2501648+jyviko@users.noreply.github.com>
Date: Sat, 17 Oct 2026 10:56:58 -0400
Subject: [PATCH] docs: ask for pictures in issues and pull requests

The bug template's Evidence asks for a screenshot or recording first,
marked up, and a section for meshes; the feature template gains a
Pictures field; the pull request template and CONTRIBUTING ask for
before/after pictures of any visible change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UhhZMBTviDQxZvwnyP89fo
---
 .github/ISSUE_TEMPLATE/bug.yml     |  3 ++-
 .github/ISSUE_TEMPLATE/feature.yml |  5 +++++
 .github/pull_request_template.md   |  4 ++++
 CONTRIBUTING.md                    | 11 ++++++++++-
 4 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
index 7a69ae8..90fc93d 100644
--- a/.github/ISSUE_TEMPLATE/bug.yml
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -24,7 +24,8 @@ body:
     id: evidence
     attributes:
       label: Evidence
-      description: Screenshots, log output, numbers. For a crash, attach the crash report (`fieldcraft-cli crashes`, then `crashes show <id>`).
+      description: |
+        Pictures first: for anything you can see (the view, a mesh, a panel, a plot), drag a screenshot or a short screen recording in here, and mark the problem on it. For a mesh, a section through it (`fieldcraft-cli snapshot … --section`) shows what the outside hides. Then log output and numbers. For a crash, attach the crash report (`fieldcraft-cli crashes`, then `crashes show <id>`).
   - type: textarea
     id: expected
     attributes:
diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml
index 489165e..f5800da 100644
--- a/.github/ISSUE_TEMPLATE/feature.yml
+++ b/.github/ISSUE_TEMPLATE/feature.yml
@@ -21,6 +21,11 @@ body:
     attributes:
       label: Expected behaviour
       description: What FieldCraft should do, as precisely as you can.
+  - type: textarea
+    id: pictures
+    attributes:
+      label: Pictures
+      description: A screenshot of where it would go, a sketch, or a picture of the result you are after. Drag images in here.
   - type: textarea
     id: reference
     attributes:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 2b7614e..3408f9b 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -2,10 +2,14 @@ Closes #
 
 ## What and why
 
+## Before and after
+<!-- For any visible change (the view, meshes, panels, results, icons): a picture before and after. Drag them in here. -->
+
 ## How it was verified
 <!-- Tests added or changed; oracle cases (tests/oracle) for solver and meshing results, with their cited references. -->
 
 ## Checklist
 - [ ] The issue was assigned to me before I started (see CONTRIBUTING.md)
 - [ ] `cargo fmt --all`, `cargo clippy -p <crates I touched> --all-targets -- -D warnings` and their tests pass
+- [ ] Before/after pictures for any visible change
 - [ ] No code, text or data from GPL-family projects or commercial CAE products
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 58c54c0..0be8384 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -68,6 +68,13 @@ Every change starts from an issue, and only the maintainer merges.
 
 Issues labelled **in progress** are being worked on by the core team; please don't start on them.
 
+## Reporting a problem or an idea
+
+Use the templates under **New issue**. Show it: for anything you can see — the view, a mesh, a
+panel, a plot — add a screenshot or a short screen recording (drag it into the issue) and mark
+the problem on it. For a mesh, a section (`fieldcraft-cli snapshot … --section`) shows what the
+outside hides. A picture is often the fastest way for someone else to see what you see.
+
 ## Making the change
 
 1. Branch from `develop` (the trunk; `main` holds released code only) and open the pull request
@@ -78,7 +85,9 @@ Issues labelled **in progress** are being worked on by the core team; please don
 3. User-visible behaviour is a command (`crates/engine/src/cmd/`) with tests, including hostile
    parameters.
 4. Meshing and solver algorithms cite the paper they come from in the module docs.
-5. Never contribute code, text or data from GPL-family projects or commercial CAE products
+5. A change you can see (the view, meshes, panels, results, icons) shows a picture before and after
+   in the pull request.
+6. Never contribute code, text or data from GPL-family projects or commercial CAE products
    (see [docs/adr/0001-libraries.md](docs/adr/0001-libraries.md)).
 
 By contributing you agree your work is licensed under MIT OR Apache-2.0.