docs: align issues and ADRs with ARCHITECTURE.md guidance #256
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation changes are correct for the lines modified, but ADR-024 needs more comprehensive updates.
The PR correctly marks the Heartbeat Configuration section as superseded, but ADR-024 contains extensive heartbeat discussion throughout the Rationale and Alternatives sections (lines 130-236) that remains unmarked. This creates confusion: readers see "superseded by ADR-026" in one section, then encounter multiple sections explaining heartbeat design decisions as current guidance.
Specific stale content still present:
- Line 140: Table row for "Heartbeat interval"
- Lines 148, 150: Examples with heartbeat_interval parameters
- Lines 156-170: Two sections explaining heartbeat design rationale
- Lines 185, 192: Consequences mentioning heartbeat
- Line 204: Constraint about heartbeat mechanism
- Lines 210, 220-236: Alternatives discussing heartbeat approaches
Recommendation: Either strike through these sections with supersession notes, or move them to a "Historical Context" appendix. ADR documents should preserve history, but make it clear what's current vs superseded.
- Create ADR-027 for Projector Poll and Retry Configuration - Captures the still-valid poll config and event retry config from ADR-024 - Documents two separate configuration concerns with clear rationale - References ADR-026 for coordination (no heartbeat needed) - Mark ADR-024 as fully superseded - Superseded by ADR-027 (configuration) and ADR-026 (coordination) - Retained for historical context only - Remove stale heartbeat references from projection.rs doc comments This properly separates the still-valid configuration guidance (ADR-027) from the superseded heartbeat/liveness detection (handled by ADR-026's session-scoped advisory locks on dedicated connections).
jwilger
force-pushed
the
fix/237-align-issues-with-architecture
branch
from
1b7f4ad to
91bf43d
Compare
There was a problem hiding this comment.
ADR-024 body still contains extensive heartbeat content (lines 104-111, 140-142, 150, 158-170, 187, 194, 222-238) presenting it as current guidance, contradicting the supersession note. This creates confusion: header says heartbeat was eliminated by ADR-026, but body explains heartbeat design in detail.
Recommendation: Strike through these sections with inline supersession notes, or move them to a "Historical Context" appendix. ADR-027 correctly extracts the still-valid content, but ADR-024 needs cleanup to match its superseded status.
No, that's not how ADRs work. If it says it's superseded, then it's superseded. We don't cross out the whole damned document. |
jwilger
dismissed
claude[bot]’s stale review
Invalid reasoning. Misunderstanding of ADR process.
## 🤖 New release
* `eventcore-macros`: 0.4.0 -> 0.5.0
* `eventcore-types`: 0.4.0 -> 0.5.0 (✓ API compatible changes)
* `eventcore-postgres`: 0.4.0 -> 0.5.0 (✓ API compatible changes)
* `eventcore`: 0.4.0 -> 0.5.0 (⚠ API breaking changes)
* `eventcore-memory`: 0.4.0 -> 0.5.0 (✓ API compatible changes)
* `eventcore-testing`: 0.4.0 -> 0.5.0 (✓ API compatible changes)
### ⚠ `eventcore` breaking changes
```text
--- failure enum_variant_added: enum variant added on exhaustive enum ---
Description:
A publicly-visible enum without #[non_exhaustive] has a new variant.
ref: https://doc.rust-lang.org/cargo/reference/semver.html#enum-variant-new
impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.45.0/src/lints/enum_variant_added.ron
Failed in:
variant ProjectionError:LeadershipError in /tmp/.tmpKfk26o/eventcore/eventcore/src/projection.rs:532
```
<details><summary><i><b>Changelog</b></i></summary><p>
## `eventcore-macros`
<blockquote>
##
[0.3.0](eventcore-macros-v0.2.0...eventcore-macros-v0.3.0)
- 2025-12-27
### Refactoring
- *(release)* switch to workspace version inheritance for full lockstep
versioning ([#221](#221))
</blockquote>
## `eventcore-types`
<blockquote>
##
[0.5.0](eventcore-types-v0.4.0...eventcore-types-v0.5.0)
- 2025-12-31
### Features
- add ProjectorCoordinator trait and PostgreSQL advisory lock
implementation ([#259](#259))
- implement run_projection free function (ADR-029)
([#263](#263))
</blockquote>
## `eventcore-postgres`
<blockquote>
##
[0.5.0](eventcore-postgres-v0.4.0...eventcore-postgres-v0.5.0)
- 2025-12-31
### Features
- add ProjectorCoordinator trait and PostgreSQL advisory lock
implementation ([#259](#259))
- implement run_projection free function (ADR-029)
([#263](#263))
</blockquote>
## `eventcore`
<blockquote>
##
[0.5.0](eventcore-v0.4.0...eventcore-v0.5.0)
- 2025-12-31
### Documentation
- align issues and ADRs with ARCHITECTURE.md guidance
([#256](#256))
### Features
- implement run_projection free function (ADR-029)
([#263](#263))
</blockquote>
## `eventcore-memory`
<blockquote>
##
[0.5.0](eventcore-memory-v0.4.0...eventcore-memory-v0.5.0)
- 2025-12-31
### Features
- add ProjectorCoordinator trait and PostgreSQL advisory lock
implementation ([#259](#259))
- implement run_projection free function (ADR-029)
([#263](#263))
</blockquote>
## `eventcore-testing`
<blockquote>
##
[0.5.0](eventcore-testing-v0.4.0...eventcore-testing-v0.5.0)
- 2025-12-31
### Features
- add ProjectorCoordinator trait and PostgreSQL advisory lock
implementation ([#259](#259))
</blockquote>
</p></details>
---
This PR was generated with
[release-plz](https://github.com/release-plz/release-plz/).
Summary
Create ADR-027: Projector Poll and Retry Configuration
Mark ADR-024 as fully superseded
Remove stale heartbeat references from projection.rs doc comments
Add .github-project configuration file
This properly separates the still-valid configuration guidance (ADR-027) from the superseded heartbeat/liveness detection (handled by ADR-026's session-scoped advisory locks on dedicated connections).
Related Issues Updated (outside this PR):
Test plan
cargo fmt --allpassescargo clippy --all-targets --all-features -- -D warningspassescargo nextest run --workspacepasses (150 tests)Closes #237 partially (documentation alignment only)