From 735f5ceaa0f14b92605e41c1c643a26258566095 Mon Sep 17 00:00:00 2001
From: Klaas van Schelven <klaas@vanschelven.com>
Date: Tue, 29 Jul 2025 14:05:18 +0200
Subject: [PATCH] Copilot instructions; another attempt

after having seen copilot in action on #171
---
 .github/copilot-instructions.md | 66 +++++++++++++++++++++------------
 1 file changed, 42 insertions(+), 24 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2a68040..6d0c532 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -3,39 +3,57 @@ abstract generality. Python 3.12 is the standard environment.
 
 ## Coding Guidance
 
-* Keep it clear and simple.
+* Keep it clear and simple. When in doubt: shorter.
 * Use descriptive names, short functions, minimal boilerplate.
-* Avoid overly clever or verbose code -- this isn't Java.
-* Avoid overcommenting: only comment to explain unusual or complex logic or
-  design decisions
+* Error-handling: avoid catching every possible error; in many cases "fail early"
+  is in fact the idiom which gives much more clarity, especially in utilities.
+* Avoid overly clever or verbose code
+* Keep comments absolutely minimal: only comment to explain unusual or complex
+  (which there shouldn't be anyway)
 * Follow PEP8 and ensure `flake8` passes (CI ignores E741, E731). width: 120 columns.
-* Use Django idioms: models, views, middleware, etc.
+* Use Django's function-based views
 
-## Tests
+### Tests
 
-* Prefer a few focused unit tests around testable logic.
-* Broader integration tests are fine to exercise key flows.
-* It's OK to generate simple coverage-style tests — just mark them with:
-  `# LLM-generated test for coverage`
+Tests should be either of 2 kinds:
 
-### Further details
+1. Tight unit-tests around easy-to-test, small, functions. These should express intent
+   clearly and enumerate the relevant cases (and no others) very carefully. The data
+   here will be very "synthetic", focussed on expressing intent
 
-##### Database
+2. Broader "integration-like" tests: much more end-to-end, with the goal of covering
+   [a] the integration of parts and [b] the happy paths for those. These tests should
+   not try to enumerate every single case. They should reflect a more typical flow fitting
+   "what would typically happen" (more natural inputs/outputs, no extensive edge-cases)
 
-* Bugsink assumes a single-writer DB model (no write concurrency).
-* Keep writes short
-* Use `bugsink/transaction.py` helpers like `@durable_atomic` etc.
+### Database
 
-##### Frontend (Tailwind)
+Bugsink assumes a single-writer DB model:
 
-* Bugsink doesn't have a backend/frontend split: "classic django instead"
+* Keep writes as short as possible
+* Do not worry about write-concurrency (there is none)
+* Use the helpers in `bugsink/transaction.py` helpers like `@durable_atomic`
+
+### Frontend (Tailwind)
+
+* Bugsink does NOT have a "modern" backend/frontend split: "classic django instead"
 * Bugsink uses Tailwind via `django-tailwind`
-* Before committing, build the CSS and add it:
-  `python manage.py tailwind build && git add theme/static/css/dist/styles.css`
-  (this is done automatically if you use the pre-commit hook from the repo root)
 
-##### Other
+Test the frontend by running the server like so and checking in a browser:
 
-* Use function-based views by default.
-* Use `python manage.py runserver` (uses `bugsink.settings.development`)
-* The default SQLite setup should work out of the box.
+`python manage.py runserver` (uses `bugsink.settings.development`)
+
+(an admin/admin user is available in your environment)
+
+### Before committing
+
+A pre-commit hook is installed in your environment and will block any illegal commit.
+Before commiting, _always_ run the following:
+
+```
+python manage.py tailwind build
+git add theme/static/css/dist/styles.css
+tools/strip-trailing-whitespace.sh
+```
+
+If you fail to do so the pre-commit hook will trigger, and you will not be able to commit.