microsoft / microsoft/simplechat
Every PR serialises through one hand-edited VERSION line, causing conflicts unrelated to the code under review
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 152
- Forks
- 116
- Avg merge
- 7h 7m
- Merged PRs (30d)
- 122
Description
## Summary
Every PR hand-edits the same `VERSION` line in `application/single_app/config.py` and adds a matching `### **(vX.XXX.XXX)**` heading to `docs/explanation/release_notes.md`. With one PR in flight that is fine. With six, it serialises the whole queue through two lines, and a large share of the resulting merge conflicts have nothing to do with the code being reviewed.
Raised by the PR merge orchestration session after coordinating six concurrent admin-settings-V2 PRs. Their assessment, which matches what I saw resolving #1425:
> six PRs serialising through one integer in one file is the underlying problem — the assignment scheme managed the symptom
## What actually happened
- #1418 and #1424 collided on the `VERSION` line twice inside ten minutes.
- The orchestrator moved to **pre-assigning** version numbers per PR (`0.261.061`, `063`, `065`, `070`, `071`, `072`…) to stop the collisions.
- The base branch then advanced five times while #1425 was resolving, and the pre-assignment had to be reissued **three times** (`072` → `080` → `082`) as the queue reordered. Each reissue meant re-editing `config.py`, the release-notes heading, and the version literal in every functional test header touched by that PR.
- None of that churn was about the substance of any PR.
The scheme worked — nothing shipped with a duplicate or regressed version. It just cost a lot of coordination for something no human was reading during review.
## Why the conflict is structural
Both contended edits are *append-at-the-top* operations on a shared line:
| File | What every PR does |
|---|---|
| `application/single_app/config.py` | Replaces the single `VERSION = "..."` line |
| `docs/explanation/release_notes.md` | Inserts a new `### **(vX.XXX.XXX)**` section at the top |
Git cannot auto-merge either, because both sides changed the same line or inserted at the same anchor. The result is a guaranteed conflict between any two concurrent PRs, independent of whether they touch any of the same code.
## Suggested direction
Not proposing a specific mechanism, but the shape worth considering is **deriving the patch bump at release time rather than hand-editing it per PR**:
- Let PRs declare *that* they change the application, not *which number* they land as — for example a changelog fragment file per PR (`docs/release_notes.d/.md`), which is conflict-free because each PR adds its own file. The release step concatenates fragments and assigns the number.
- Compute `VERSION` at build or release time from commit count or tag, so `config.py` is not edited per PR at all.
- Keep the current convention for the major/minor segments, which are deliberate decisions, and only automate the third.
Any of these removes the two lines that currently serialise everything.
## What already works and should be kept
`functional_tests/test_support/versioning.py` already provides `assert_app_version_at_least`, and the repository instructions require tests to use it rather than asserting exact equality. That is the right call and it means **test assertions are already immune** to renumbering — a pre-assignment change does not invalidate them. The remaining cost is purely the hand-edited literals in headers and docs.
For scale: 236 files currently contain a `0.261.x` literal (105 under `docs/`, 124 under `functional_tests/`, 7 under `application/`). Most are historical records that correctly should not move. The problem is narrowly the two lines that every new PR must edit.
## Caveats
- This touches a documented repository convention (`.github/instructions`, version management), so it needs a deliberate decision rather than a drive-by change.
- Deriving the version from commit count or tags changes what the number means, which may matter for support and for the deployer, which tracks its own version separately in `deployers/version.txt`.
- Low urgency. It only bites when several PRs are in flight at once, which is exactly when it bit.
## Context
Observed across PRs #1415, #1418, #1419, #1421, #1422, #1424, #1425 and #1426 during the admin-settings-V2 work.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read the version-management guidance in .github/instructions, then inspect application/single_app/config.py, docs/explanation/release_notes.md, functional_tests/test_support/versioning.py, and deployers/version.txt. Compare the possible release-time approaches against the documented convention and deployer expectations; done means an agreed mechanism is implemented without requiring every PR to edit the shared version line and release-notes heading.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, documentation, release
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100