| 1 |
# mssql-django Gated PR Self-Check |
| 2 |
|
| 3 |
Use this prompt before merging any backend/compiler/schema PR. |
| 4 |
|
| 5 |
## Objective |
| 6 |
|
| 7 |
Run a **merge gate** that prevents regressions from: |
| 8 |
- contract ambiguity, |
| 9 |
- double-escaping/double-transforms, |
| 10 |
- fast-path branches bypassing shared safety logic, |
| 11 |
- stale test exclusions, |
| 12 |
- insufficient integration proof. |
| 13 |
|
| 14 |
The output must be a clear **PASS / FAIL / BLOCKED** decision with evidence. |
| 15 |
|
| 16 |
## Inputs |
| 17 |
|
| 18 |
- PR branch name |
| 19 |
- Target branch (usually `dev`) |
| 20 |
- Changed files (`git diff --name-only <target>...HEAD`) |
| 21 |
- Related Django test modules for changed areas |
| 22 |
|
| 23 |
## Required Checks (in order) |
| 24 |
|
| 25 |
### 1) Contract change declared |
| 26 |
For every behavior-changing helper/symbol, declare one explicit contract: |
| 27 |
- who returns raw values, |
| 28 |
- who escapes/normalizes, |
| 29 |
- where transformation happens, |
| 30 |
- and whether call sites must change. |
| 31 |
|
| 32 |
### 2) All call sites audited |
| 33 |
Audit all consumers of changed symbols and verify: |
| 34 |
- contract applied exactly once, |
| 35 |
- no mixed old/new behavior, |
| 36 |
- no hidden secondary escaping/transform. |
| 37 |
|
| 38 |
### 3) Fast-path invariants preserved |
| 39 |
If a fast-path exists (special-case `continue`/`return`/short-circuit), prove it does not bypass shared safety logic: |
| 40 |
- ORDER BY dedupe, |
| 41 |
- alias handling, |
| 42 |
- parameter ordering, |
| 43 |
- escaping rules, |
| 44 |
- pagination/order requirements. |
| 45 |
|
| 46 |
If it does bypass shared logic, fix by integrating with shared path, not by adding ad-hoc string post-processing. |
| 47 |
|
| 48 |
### 4) Integration test proof |
| 49 |
Provide end-to-end proof for each behavior change: |
| 50 |
- Add local regression tests under `testapp/tests/` when applicable. |
| 51 |
- Run upstream Django tests that exercise the same path. |
| 52 |
- Include at least one regression that targets the **risky edge** (duplicate/equivalent path, alias path, mixed type path, etc.). |
| 53 |
|
| 54 |
### 5) Doc/comments synced |
| 55 |
Ensure comments and PR description match current behavior: |
| 56 |
- remove stale “still failing” language if test now passes, |
| 57 |
- add concise reasons for any remaining exclusions. |
| 58 |
|
| 59 |
### 6) Exclusion hygiene (strict) |
| 60 |
For any exclusion touched in `testapp/settings.py`: |
| 61 |
- Verify candidate removals under **normal settings** (`testapp.settings`), not only fast profile. |
| 62 |
- If using `settings_fast`, treat as exploratory only; confirm final decision with `testapp.settings`. |
| 63 |
- Keep only exclusions that are proven failing due to true SQL Server limitation or out-of-scope known issue. |
| 64 |
|
| 65 |
### 7) Version matrix evidence |
| 66 |
Run targeted tests plus HOT guard matrix and report: |
| 67 |
- PASS lanes, |
| 68 |
- FAIL lanes, |
| 69 |
- BLOCKED lanes with concrete environment reason. |
| 70 |
|
| 71 |
## Merge Gate (must all be true) |
| 72 |
|
| 73 |
- No unresolved contract ambiguity. |
| 74 |
- No double-escaping / double-transform pattern in call sites. |
| 75 |
- No fast-path branch bypassing shared invariants without explicit handling. |
| 76 |
- Integration regression proof exists for each behavior change. |
| 77 |
- Exclusion changes are validated under `testapp.settings`. |
| 78 |
- Targeted tests green + HOT guard green (or BLOCKED with environment reason). |
| 79 |
- PR description includes root cause, fix scope, and exclusions touched. |
| 80 |
|
| 81 |
## Recommended Evidence Commands |
| 82 |
|
| 83 |
```bash |
| 84 |
# Diff scope |
| 85 |
git --no-pager diff --name-status origin/dev...HEAD |
| 86 |
git --no-pager diff --stat origin/dev...HEAD |
| 87 |
|
| 88 |
# Local backend tests |
| 89 |
python manage.py test testapp.tests --verbosity 2 |
| 90 |
|
| 91 |
# Targeted local module |
| 92 |
python manage.py test testapp.tests.test_jsonfield --verbosity 2 |
| 93 |
|
| 94 |
# Upstream targeted test(s) |
| 95 |
cd django |
| 96 |
PYTHONPATH=/workspaces/mssql-django/django python tests/runtests.py --settings=testapp.settings <module.or.test> |
| 97 |
|
| 98 |
# HOT matrix / CI guard |
| 99 |
# Run or verify the HOT matrix / CI guard workflow for this branch in your CI system |
| 100 |
# and record its status (PASS / FAIL / BLOCKED) in the gate summary. |
| 101 |
``` |
| 102 |
|
| 103 |
## Required Output Format |
| 104 |
|
| 105 |
### Gate Summary |
| 106 |
- Overall: PASS / FAIL / BLOCKED |
| 107 |
- Scope: changed files + behavior areas |
| 108 |
|
| 109 |
### Checklist Results |
| 110 |
- Contract change declared: PASS/FAIL (+ evidence) |
| 111 |
- Call-site audit: PASS/FAIL (+ evidence) |
| 112 |
- Fast-path invariants: PASS/FAIL (+ evidence) |
| 113 |
- Integration test proof: PASS/FAIL (+ tests run) |
| 114 |
- Doc/comments sync: PASS/FAIL (+ note) |
| 115 |
- Exclusion hygiene: PASS/FAIL (+ list kept/removed) |
| 116 |
- Version matrix evidence: PASS/FAIL/BLOCKED (+ lanes) |
| 117 |
|
| 118 |
### Exclusions Decision Table |
| 119 |
For each touched exclusion: |
| 120 |
- test id |
| 121 |
- decision (keep/remove) |
| 122 |
- reason |
| 123 |
- proof command |
| 124 |
- result |
| 125 |
|
| 126 |
### Merge Recommendation |
| 127 |
- Merge now / Needs fixes |
| 128 |
- If fixes needed, list minimal required changes. |
| 129 |
|
| 130 |
## Notes specific to mssql-django |
| 131 |
|
| 132 |
- `testapp/runners.py` marks excluded tests as expected-failure (`x`) under normal settings. Do not treat `x` alone as proof of backend failure for exclusion decisions. |
| 133 |
- For exclusion removal decisions, always re-run candidate tests directly under `testapp.settings` and inspect actual pass/fail outcomes. |
| 134 |
- Prefer expression-level/compiler-level fixes over SQL string surgery. |