Taking a change upstream

This guide takes one change from a fresh branch to an open pull request against upstream, by way of stable. Why the branches are laid out this way is on Branches and workflow.

Before you start

What you'll have

The change on its own branch, merged into stable so you can play on it, and a pull request open against upstream's game_rework.

Set up two working trees

Do this once. From your clone:

git worktree add ..\NexusForever.stable stable

Run the server from the stable worktree and develop in the main one, so a build never fights the running server's locked files.

Build the change

Cut a branch

Cut it from game_rework, or from the branch your change depends on:

git switch game_rework
git switch -c <change-name>

Name it after the change, in lowercase words with hyphens: archive-packet-ids, base-entitlements. Keep it to one concern. If you find a second one while you work, give it its own branch.

Write it upstream's way

Write anything that might go upstream to upstream's standard: Contributing code style for how the code looks, and Contributing code patterns for where it goes and how it's wired. Where the code holds an old and a new pattern side by side, follow the new one. Leave the style of code you only touch as it is. Contributing covers which rule wins when they disagree, and what we add on top.

Leave out tests and Docker files: upstream removes the first and refuses the second.

Commit messages are past-tense sentences with a full stop: "Corrected the Galactic Archive article id to 14 bits."

Check it in game

Build it, run it, and see it work, following Verifying a feature.

Important

A change that only compiles isn't ready for stable.

Ship it

Merge it into stable

git switch stable
git merge --no-ff <change-name>
git push origin stable

If you use the second worktree, run this there.

Open the pull request

1. Push the branch: git push -u origin <change-name>.
2. Open a pull request from rebaserHEAD:<change-name> against NexusForever:game_rework. Combat, AI and instance work targets expedition-evil-from-the-ether instead.
3. Title it the way it should read in upstream's history: a squash lands under the title.
4. Write the body as a few plain paragraphs: what it does, anything it builds on ("Builds on #587"), and what was tested and what wasn't.
5. Leave Allow edits by maintainers ticked.

What reviewers ask for, and how a pull request lands, is on Contributing pull requests.

After review

Put review fixes on the branch as new commits, push them, and merge the branch into stable again.

Warning

Don't rebase or force-push a branch with an open pull request.

Troubleshooting

Symptom	Cause	Fix
The build fails with locked files	The stack is running from the tree you're building	Build in the other worktree, or stop the stack
Your pull request shows another change's commits	It's cut from a branch whose pull request hasn't merged yet	Expected; say "Builds on #N" in the body
A merge into stable conflicts on a migration	Upstream added one beside ours	See Syncing with upstream