Contributing

Contributing

Bug reports, translation corrections, missing item names and code changes are all welcome. PCEdit is GPL-3.0-or-later; by contributing you agree your work ships under that licence.

Good first contributions

Contribution	Where to start
A missing item name or icon	Item Catalog
A translation correction	Localization
A bug report	FAQ & Troubleshooting has the details to include
Testing the macOS build	Nobody has confirmed it — reports are genuinely useful
A Linux distro report	The WSL matrix in Building & Packaging

The change workflow

This is the flow for any feature, behaviour change, or bug fix. It does not apply to answering a question or a read-only investigation.

1. Plan first, in phases

Investigate the real code and data before proposing anything, then write a multi-phase plan. Each phase must end in a working, committable state — tests green, nothing half-applied — so the work can stop or be reviewed at any phase boundary.

The plan states: why the change is being made, what each phase does, the files it touches, the existing helpers it reuses, and how to verify the result end to end. Where a decision is open, give a recommendation, not a neutral list of options.

2. Stress-test the plan before it is accepted

Challenge each branch of the decision tree while assumptions are still cheap to change. Raise concerns with the request at this point, not after the code is written. If the requester reaffirms, that is the decision — build it in full.

3. Branch only once the plan is accepted

Never commit directly to main. Branch from an up-to-date main:

git checkout main && git pull --ff-only && git checkout -b <topic-branch>

If main cannot fast-forward, resolve that before branching.

4. Commit at the end of every phase

One commit per completed phase — not one commit for the whole plan. Before each commit:

1. Build.

2. Run both test projects.

3. If you changed a PackageReference, run dotnet restore and commit the updated packages.lock.json files — CI's locked restore rejects the change otherwise.

4. Regenerate any generated file the phase touched:

   python tools/i18n/gen_satellites.py          # CI fails on drift
   python tools/i18n/gen_metainfo.py            # CI fails on drift
   python tools/item-catalog/gen_catalog.py     # CI fails on drift (since v1.4.1)

Commit messages say what changed and why.

Important

Never add a Co-Authored-By: Claude … (or any AI assistant) trailer to a commit message.

5. Bump the version and write the changelog entry — before opening the PR

The final phase bumps <VersionPrefix> in the repo-root Directory.Build.props:

Change	Bump
Bug fix	patch
Feature, or new game-version support	minor
Breaking change	major

Doing it inside the PR is what leaves main immediately releasable after the merge.

The same phase adds the entry to CHANGELOG.md — a ## vX.Y.Z section at the top of the list, in the voice of the existing entries: what changed for someone using the app, not what changed in the code. A version bump carrying user-visible change but no entry is an incomplete phase; that is exactly how v1.2.0 and v1.2.1 came to ship undocumented.

Call out anything user-visible beyond the fix itself — a size change, a new or dropped runtime dependency, a renamed artifact, a raised minimum OS — and say which platforms are not affected.

The one exception is a bare bump for development after a release, which carries nothing yet; its entry arrives with the change that fills the version.

What CI will check

• Every project's dependencies match its committed packages.lock.json — on Linux, Windows and macOS runners.
• Both test projects pass.
• PCEdit.Desktop builds.
• A linux-x64 publish carries app-local ICU.
• The generated localization satellites, AppStream metadata and item catalog match their generators — commit them.
• The Avalonia build-telemetry opt-out is still in effect.
• <VersionPrefix> is well-formed and not behind the newest release tag.

House rules worth knowing before you write code

• Mutate through ISaveFileWorkspace. ViewModels never build a modified save themselves.
• Use with expressions. Never hand-copy every property of a model — that is how fields have been silently dropped on save before.
• A version-added save key is nullable, so older saves do not gain it. See Save File Library.
• Keep PCEdit.App.Core free of any UI-framework reference. Platform concerns go behind an interface.
• Don't hand-edit generated files: the satellite .resx, the AppStream XML, ItemCatalog.json.
• Don't let a test overwrite a fixture save, and never let Interplanetary-2.102.json gain a BOM. See Testing.

Reporting a bug

Open an issue with your OS and install method, the PCEdit version from the About page, the game version and platform, and what you did versus what happened. Please don't attach a save file unless asked — they are large and carry your player name.