Repository navigation
docs: add refactoring backlog (deferred internal refactors) - #67
Conversation
A versioned, grouped-by-file list of refactors too big/risky to fold into the change at hand - captured for quiet time instead of GitHub issues (overkill for a solo maintainer, and keeps the fork tracker signal). Cross-cutting/architectural items (thread model / poll+control merge, God-class split, static-state removal, actor-IPC) link to upstream #200/#488/#524/#325/#405 and the abandoned draft branches as design refs rather than being rewritten. Seeded from a code scan (TODO/FIXME + large-class signals) and a branch/issue/prior-PR sweep. AGENTS.md documents the // TODO(refactor): marker convention, the doc boundaries (vs inflight / upstream-map / solutions / PR review), and the graduation rule. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
❌ Duplicate Code ReportTwo engines run in parallel for cross-validation. Each has its own thresholds tuned to its baseline - the real safety net is the per-engine "max increase vs base" check. ✅ PMD CPD
No new clones introduced by this PR. ❌ jscpd (language-agnostic)
No new clones introduced by this PR. Powered by astubbs/duplicate-code-cross-check |
✅ SpotBugs ReportNo bugs found (new bugs only — baseline from base branch excluded). |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #67 +/- ##
============================================
- Coverage 77.77% 77.70% -0.08%
- Complexity 75 1166 +1091
============================================
Files 82 82
Lines 4220 4220
Branches 386 386
============================================
- Hits 3282 3279 -3
- Misses 757 760 +3
Partials 181 181
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
❌ Mutation Testing (PIT) ReportPIT did not produce a report. Most commonly this means a test failed in the baseline (PIT runs all tests unmodified first to establish green) and PIT aborted before mutating. See the "Run PIT mutation testing" step logs for the failing test, then either fix it or add it to |
…eal index Stop brushing over the pointers. Each abandoned refactor branch now has a specific one-liner (what it did, relevance, linked issue/PR) grouped by theme: thread-model/actor cluster (upstream #200), static-state removal, shard-count caching perf (#530), engine/queue experiments (confluentinc#884), encoding, offsets/state classes (#233), API/interface, test infra. Records dead-ends explicitly (e.g. producer-facade, whose branch concluded it was not worthwhile) and supersessions (loom -> upstream confluentinc#908). The bulk verdicts for the ~53 prior closed PRs stay in upstream-pr-analysis.adoc; this index keeps the actionable pointers with issue links. Also added the two other synchronized(this) lock-hygiene sites (ProducerManager.syncBeginTransaction, DynamicLoadFactor.doStep) surfaced while checking the PR #57 fix. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| @@ -0,0 +1,246 @@ | |||
| # Refactoring backlog | |||
There was a problem hiding this comment.
this is good. but you should separately track of breaking change that we have identified should be made, but need to wait until the next major version is being prepared. Something like "breaking changers queued for next major version".
|
Claude finished @astubbs's task in 1m 41s —— View job Review complete ✅
This is a well-executed, low-risk docs-only PR. Summary of what I checked and found: Accuracy — verified, all correct. I spot-checked ~20 of the file/line references against the actual source ( Structure. Grouping by file (rather than by theme) is a reasonable choice for a solo-maintainer backlog — it's the right tradeoff for "surface it when I'm already editing this file" over "browse by category," and the cross-cutting section correctly catches the handful of architectural items that don't have one home. The doc boundaries section in Minor observations (non-blocking):
No code changes, so no build/test impact — CI's duplicate-code and coverage bots flagged pre-existing repo-wide numbers unrelated to this PR (0.00% change vs base in both). Verdict: Solid, accurate, appropriately scoped. Nothing here needs to change before merge. |
- Add a dedicated "Breaking changes queued for next major version" section (release-gated, kept apart from the non-breaking refactors), consolidating the deprecated commitInterval/options removals, JStream removal, enum rename, and nonnull/module-info candidates. Slim the by-file entries to back-references. - Pin every abandoned origin/<branch> reference to its current short SHA so the catalogue survives future branch cleanup; expand the brace-compressed lists. - Disambiguate bare upstream refs that collide with fork branch names (confluentinc#857/confluentinc#859/confluentinc#908 -> upstream #NN) and note the convention that branch names encode the upstream number. - Explain why so many draft branches exist: the fork was a personal experiment space before becoming the project's primary; mine them for ideas, then prune. - AGENTS.md: mention the new release-gated breaking-changes section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review feedback addressed —
|
|
Claude finished @astubbs's task in 1m 7s —— View job Review feedback addressed —
|
Bring #57 current with master (release-notes #72, deps refresh #73/#74, unit-suite parallelisation #68, refactoring backlog #67, self-hosted CI, etc.). Only CHANGELOG.adoc conflicted: the 0.6.0.0 Fixes now lists master confluentinc#892 (per-commit OffsetMapCodecManager fix) alongside this PR confluentinc#859 (List->Set + assignment-path caching) and confluentinc#893 - complementary, kept all three. Regenerated README.adoc from the merged CHANGELOG via the asciidoc-template plugin. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2 participants
Why
Refactor opportunities get noticed constantly while working, but many are too big or too risky to fold into the change at hand. A GitHub issue per item is overkill for a solo maintainer and would dilute the fork tracker (kept for signal; the upstream tracker is the mining ground). This adds a lightweight, versioned backlog instead.
What
docs/refactoring.md- deferred internal refactors, grouped by file (localises merge conflicts and surfaces items when you are editing that file), with a Cross-cutting / architectural section for the ones that have no single home file.AGENTS.md- documents the// TODO(refactor):code-marker convention, the doc boundaries (vsinflight.md/upstream-map.yaml/docs/solutions// PR review), and the "graduate to a branch/PR only when you actually start it" rule.Seeded from a code scan (TODO/FIXME + large-class signals) and a sweep of branches, open issues, and the closed-unmerged upstream PRs catalogued in
upstream-pr-analysis.adoc. The big architectural items - the poll+control thread-model merge (upstream #200), God-class split (upstream #488), static-state removal (upstream #405/#126 → parallel tests #143), actor/IPC (upstream #524/#325) - link to the upstream issues and the abandoned draft branches as design refs rather than being rewritten here. If an item maps to an upstream issue it is linked, not duplicated.Docs-only; no code changes.
🤖 Generated with Claude Code