Contributor's Guide

Reporting bugs

Please report bugs in the issues tracker. Please try to be as specific as possible.

Getting Started with SWP and git

1. Set up git
2. Fork this repo and then clone your fork to your local machine.
3. Make your changes.
4. Commit them (git add the files that have changed, git commit them, and then git push them back to github).
5. Submit a pull request, or point me to your changes on the forum
6. Celebrate, because you're awesome!

If you're an advanced git user, you're encouraged to use feature branches if you're going to be making a lot of related changes. Likewise we suggest you make your changes based upon gold, or a feature branch your changes depend upon (like dfhack_r4), as the beta branch is really just an amalgam of features, rather than a proper development branch in and of itself.

If you're still new to git, don't worry about the preceeding paragraph. Just do what feels best; git makes it easy to apply patches to the right place. However we do encourage you to commit early and often; little commits each making a set of related changes are easier to manage than larger commits which may involve changing different features.

Switching between versions

Git makes it super-easy to switch between versions. git checkout MWDF_4b gives you the offical 4b release, likewise you can git checkout MWDF_4c (and 4d, and 4e, and 4f, and 4g). You can see all tagged releases with git tag -l.

To see the last commit on your branch, you can git show or git log. For a quick history, git log --oneline --no-merges is great. If wish you to inspect a specific change, then git show ID with any ID (in the left column) will display what the changes are. For many people, the network view on github is particularly useful.

Keeping up to date

By default, your local repository won't update when changes are made in the main SWP repository. It would be terrible if you were working on something and the files changed beneath you!

Instead, you can choose when to integrate upstream files when it pleases you. The first step is to configure a remote that points to the main SWP repository. This only needs be done once:

$ git remote add pjf https://github.com/pjf/masterwork-dwarf-fortress.git

It's now possible to merge those changes into your own repo. Usually you'll want to merge your gold branch:

$ git fetch pjf        # Make sure you have all the remote changes

# Then, for each branch you wish to merge:

$ git checkout gold    # This puts you on your local gold branch
$ git merge pjf/gold   # This merges pjf's gold branch into yours

Commonly the gold branch is where most work is based, but you may also have reason to merge other branches if needed.

If you merge a branch by accident (it happens!) you can reset your branch to where it was before the merge with git reset --merge ORIG_HEAD.

Once you've updated your local files, you can send those changes back to github with git push.

Hints for good commits

• The first line of your commit message is treated as the title. It's what shown in github's logs, the network graph, and in various reports. It should be a short, human-readable summary of what you've done.
• The second line of a commit message (if it exists) is usually left blank for clarity.
• The remaining lines of your commit message form the body. This should contain a more detailed description of work if required.
• You can reference issues in the issues tracker by a hash-sign followed by a number. Github will auto-link them. Eg: #53 or #98.
• Commits in git are discrete changes that address a single bug or feature, and either a whole commit is applied, or none of it is. If you're fixing lots of bugs, or adding lots of features, it's best to have a separate commit for each one. This makes them easy to track, and also easy to back-out if something goes wrong.
• Don't worry too much about the rule above. If needed, we can split large commits into smaller pieces, or combine smaller commits (eg: a change and a fixup of that change) into single commits, before integrating them into the main tree.
• Use your own judgement, the guidelines are guidelines, not hard rules.
• Git makes it easy to undo changes, so be bold with your commits.

One of the best things is that provided you can use commit and push, then the project maintainer can do the rest. They can see when you've pushed commits, merge them into upstream branches, and even send you pull requests which will merge changes back into yours. So don't worry if any of the advanced commands seem hard at first, you can totally start with the basics. Github also has a bootcamp which goes through the basics, and there are lots of tutorials on-line. Don't be afraid to try things out, it's super-easy to undo things in git (that's what git revert does).

To make a pull request on github, go to the main repository pull request page and create a new request for your changes. Use 'compare across forks' to compare the branch (gold) to your branch, and submit the pull request.

Advanced: Keeping things really clean

Sometimes you'll find the local repository has differed from the upstream repository. This may be because your commits have been split or merged for their inclusion upstream. If you want to reset your local repo so your gold branch is the same as if you'd made a fresh clone, you can do so:

git fetch pjf                   # Make sure you have all the remote changes
git branch -m gold old_gold     # Relabel your 'gold' branch as 'old_gold'
git checkout -b gold pjf/gold   # Form a new 'gold' branch based on pjf/gold

If all looks good, you can force your branch on github to update with:

git push --force origin gold

The --force option is necessary because your new branch is no longer a strict continuation of your old branch, and if anyone else had based their changes off your branch, then they might be very surprised.

If you're absolutely sure, you can delete your old branch with:

git branch -D old_gold

However it's safe to leave your branch around, in case you discover later that you need something from it.

Playing in your repository

If you wish to play Masterwork in the same repository as you do development, it's best to have a dedicated play branch:

$ git checkout gold             # Or beta, or wherever you wish to branch from.
$ git checkout --track -b play  # 'play is our local branch we wish to play on.

# Edit/move/whatever your customisations. I usually run the Settings
# GUI at this point, adjust worldgen params, etc.

$ git add -A .                  # Mark all our changes for inclusion.
$ git commit                    # Commit your local customisations.

You then have a gold branch which is identical to your gold branch on github, which can be used for development. You also have a play branch that has your customisations, and which is tracking your local gold branch. The play branch is local; it won't get uploaded to github, and exists only on your machine.

You can git pull on your play branch to merge from your master branch. If there are conflicts, you can always use git checkout -- data/init to choose to use your existing files, and then git commit to mark the changes as resolved. This gives you a chance to review conflicts first.

Alternatively, git pull -s ours on the play branch will tell git to automatically favour our revisions when conflicts exist, and it's pretty darn awesome. You might be able to use git config branch.play.mergeoptions -sours to do this automatically for the play branch, but I haven't actually tested that. If that works, then it pretty much solves all our play-config options.

---

This top-post is generated automatically! You can edit it in markdown format if you think it's missing something. Be bold with your edits, they're easy to undo!