Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (99 loc) · 4.92 KB

CONTRIBUTING.md

File metadata and controls

128 lines (99 loc) · 4.92 KB
Raw

Contributing to meteor-decomp

Contributions land via forks and pull requests. The unit of work is one function: you claim a VA, write one byte-identical src/<binary>/_rosetta/FUN_<va>.cpp, and open a PR into develop. This holds whether you're a human or an automated agent.

Read PLAN.md for scope/strategy and docs/matching-workflow.md for the per-function match loop in detail. This file is the short, fork-based checklist.

The loop

fork  →  claim  →  match  →  PR into develop

1. Fork

Fork the canonical repo and clone your fork. Add the canonical repo as an upstream remote so you can keep develop in sync and target PRs at it:

gh repo fork <owner>/meteor-decomp --clone
cd meteor-decomp
git remote add upstream https://github.com/<owner>/meteor-decomp.git
git fetch upstream develop

Get the build toolchain working (VS 2005 under Wine + objdiff) — see docs/msvc-setup.md. You also need the binary's work pool, which make split BINARY=<X>.exe generates locally (the YAML is gitignored; it's regenerated, not committed).

2. Claim

Reserve the VA before you start so two people don't match the same function. Post a comment on the coordination issue:

/claim FUN_004165b0 ffxivgame

The bot replies granted / extended / rejected. Wait for granted (or extended, if it's already yours). The full protocol — lease TTL, heartbeat, pinning, auto-release — is in docs/claim-protocol.md.

Do not claim by editing config/<bin>.yaml. That file is gitignored and regenerated by make split, so an edit there is not a durable claim and will be lost. The /claim comment is the only claim mechanism.

3. Match

On a branch in your fork, write exactly one file: src/<binary>/_rosetta/FUN_<va>.cpp.

  • One file only. Don't touch shared headers (include/<bin>/…), config/, tools/, the Makefile, docs/, README.md, PLAN.md, or any other curator/coordination surface. Those make the merge harder and belong to a separate change. (See AGENTS.md for the full "don't touch what isn't yours" rules.)

  • License header. Copy the AGPL header verbatim from a sibling _rosetta/*.cpp in the same binary — don't retype it. It begins:

    // meteor-decomp — clean-room decompilation of FINAL FANTASY XIV 1.x client binaries
// Copyright (C) 2026  Samuel Stegall
// ...
// SPDX-License-Identifier: AGPL-3.0-or-later

    If your file was produced by the template stamper it may carry a leading // [STAMPED] … provenance banner above the AGPL header — that's fine; the header check accepts a stamped banner before the boilerplate.

  • GREEN is the only acceptable state. Match against the original:

    make rosetta                    # compile every staged _rosetta/*.cpp
make diff FUNC=FUN_004165b0     # byte-diff vs the original slice

    make diff returns GREEN (exit 0, every byte matches), PARTIAL (exit 1, same length, some bytes differ), or MISMATCH (exit 2). Only GREEN is committable. If you can't reach GREEN within your iteration budget, don't commit a half-match — drop the file, leave the claim to lapse (or post /unclaim), and optionally leave a post-mortem under decomp-notes/blocked/.

The 13 canonical MSVC-2005 fixes (register allocation, __thiscall, /GS cookies, x87 vs SSE, …) are in docs/matching-workflow.md § 7 and AGENTS.md.

4. Open the PR

Commit your one file and open a PR from your fork into develop:

git commit -m "decomp: match Blowfish::Init @0x004a1230"
git push origin HEAD
gh pr create --repo <owner>/meteor-decomp --base develop \
  --title "decomp: match Blowfish::Init @0x004a1230"

Opening the PR pins your claim (the lease stops expiring, however long review takes). Merging it auto-releases the claim and recomputes the progress numbers. Closing it without merging frees the VA back to the pool. You don't edit any progress/status file by hand — reconcile.yml does that on merge.

Automated contributors

The same fork → claim → match → PR flow is automated by decomp-agents distributed mode. An agent runs from its own fork under its own gh identity, claims via /claim comments, runs the same match loop + a toolchain-free PR gate, and opens upstream PRs — serialised by the same upstream claim ledger as human contributors. See ../decomp-agents/README.md § Distributed mode and docs/claim-protocol.md.

Legal

The original Square Enix .exe binaries must never be committed — fetch your own copy via the workspace installer and let tools/symlink_orig.sh make them visible to the build. Your decompiled C/C++ is original clean-room work licensed AGPL-3.0-or-later; see LICENSE.md and NOTICE.md.