meta: parallel contributions are outpacing a shared development line

Open
#218 4 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
18/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Domain
documentation

Research direction

This is a governance proposal, not a code task: read the existing CONTRIBUTING.md, then skim docs/experiments.md, CMakeLists.txt and the two competing shim PRs (#183, #189) to see the overlap the issue describes. The concrete deliverable is one paragraph in CONTRIBUTING.md stating the three milestones and the merge rule, and it is done when the maintainer agrees in this thread. The four comments so far are discussion, so a newcomer should not act until a decision lands.

Written by the indexing model from the issue text.

Description

Problem

The repository is receiving more parallel changes than it has capacity to review, verify or integrate into a coherent direction. Each change is individually defensible under the current rule ("one pull request, one reviewable behavior"), but the rule says nothing about order. The result is breadth-first growth: many correct pieces, no vertical slice.

This is not a criticism of any contributor. It is a structural observation about the current throughput.

Evidence

Snapshot of main when this was written:

  • 25 open pull requests.
  • docs/experiments.md is edited by 17 of them.
  • CMakeLists.txt is edited by 11 of them.
  • tools/pe_map.cpp by 5, tests/offscreen_check.cpp by 4, tests/cpu/native_map_check.py by 4.

Recent examples of the resulting friction:

Observation Consequence
#183 (build a desktop xmem.dll) and #189 (serve the Bink shim from era_heap) pursue the same shim contract in different directions One of them has to be reframed after the other lands; effort is duplicated
A CI failure on #212 came from tests/intake/paths_check.py:118, which encoded "an unknown loader hash produces no findings" The contract lived only inside a test; a parallel change to the same behavior broke it
The three most recent merged PRs had no review comments before merge Review capacity is not keeping pace with submission
src/ contains one 32-line runtime file Every experiment re-implements its own shim, because there is no shared layer to extend

Risks

  1. Hidden contracts. When a behavior is only expressed by a test assertion, another contributor cannot see it. Changing the behavior then looks like a regression.
  2. Duplicate directions. Two PRs can implement the same missing piece in incompatible ways, and neither author knows until both are reviewed.
  3. Review depth. With 25 open PRs, the default becomes "does CI pass" rather than "is this the right change". CI does not run the hardware tests.
  4. Rebase churn. docs/experiments.md and CMakeLists.txt are edited by almost every PR, so every merge invalidates several branches.
  5. Breadth without a vertical slice. The README's central unverified claims (title CPU execution, startup, frame rate) are not moved by any single new experiment, and no experiment is required to connect to another.
  6. Evidence drift. docs/experiments.md grows faster than anyone can audit. Platform differences appear late, for example the Windows 10 in-box WARP failing pixel_aot_warp on the NLG NaN case.
  7. Incentive mismatch. Fast merges reward volume. Contributors optimise for what is rewarded.

Proposed change

A lightweight development line plus a merge rule. No code changes, no new process tooling.

Three milestones, in order:

  1. Loader usable. pe_map plus a shared shim contract, TLS data, forwarded exports. Completion: a source-built DLL maps with every import and export resolved through one documented interface.
  2. Measured startup. EXE entry point, a TLS value read on two threads, and an initialisation log compared with a normal Windows launch (#165).
  3. One real caller. Trace a higher-level caller into the Bink allocation path, as the README's CPU row asks.

Merge rule: every new pull request states which milestone it unblocks. If it unblocks none, it is welcome but goes to a visible later list rather than competing with the current milestone. The maintainer still decides what merges; the rule only makes the cost visible.

Two supporting practices:

  • A consolidation lane: the shared lowerer, the shim contract and the capability table (#166) are first-class work, not refactors to squeeze between features.
  • Review exchange: a contributor who opens a pull request reviews one outside their own area. This is a norm, not a gate.

Alternatives

  • Status quo. Keeps momentum, but the drift persists and the vertical slice stays absent.
  • Hard freeze on new experiments. Effective, but it risks losing the contributors who are currently active.
  • Area ownership. Clearer responsibility, but heavy for a project this size and it would slow down the people already doing the work.

Verification

The proposal works if, after two weeks:

  • the open pull request count stops growing;
  • most new pull requests name a milestone;
  • at least one milestone completion condition is met;
  • duplicate directions are caught before both are implemented.

None of this needs a bot or a new label. It can be written into CONTRIBUTING.md in one paragraph if the maintainer agrees.

Scope

  • No code changes, no test changes, no new dependency.
  • No retroactive closing of open pull requests.
  • No criticism of individual contributors; the examples include the author's own work.
  • No game files, dumps, distribution links or credentials.

AI-assisted.

Dominant language
Python
Stars
696
Forks
61
Avg merge
25m
Merged PRs (30d)
171

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from R0Y00/Xbox2Windows

All issues in R0Y00/Xbox2Windows

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.