Meridian 59 Tools - GitHub Repository
For any potential contributor, the first tool they will encounter when deciding to help with the project is GitHub. GitHub is a web-based service for hosting git repositories, which allows multiple users to work on the same codebase together. This is the service we use for handling version control, pull requests (submissions from contributors) and milestones to track updates and build our test server from. Daenks maintains the ‘master copy’ of the code for server 103, and contributors work on their own local copies of it.
Getting set up on GitHub
First of all, make an account, on the GitHub website.
Next, download a git client to handle your local (on your computer) repository. I recommend GitHub for Windows and this guide will assume you are using it but there are quite a few clients available. GitHub for Windows comes with two applications we will use: the graphical interface (GitHub) and the command-line shell (Git Shell).
Follow this guide to complete the setup (GitHub may do some of this for you).
Obtaining the repository
You should now have a working copy of GitHub on your computer, so the next step is to obtain the 103 repository. Browse to our repo on the GitHub website and click the “Fork” button in the top-right hand corner. This will copy the repository to your own GitHub website. You then need to go to your GitHub website and click the “Clone in Desktop” button on the right side of the screen.
This will open up GitHub on your computer and download the repository. When finished, you should have something like this when you open GitHub:
Use the settings button (the gear in the top-right) to open up Git Shell, and run the command git remote -v.
You should have something similar to this, with origin being your GitHub account, and upstream the 103 repository. If you are missing one or both of these, use (example given for upstream)
git remote add upstream https://github.com/Daenks/Meridian59_103.git to add the missing remote.
Working on the code
At this point you should be fully set up to build your own local server and client, and to contribute changes to the codebase. The build process itself will be covered in a later post, as we are in the middle of overhauling it and adding a Visual Studio 2013 solution to make working on the game a lot easier. For the current build process, follow this guide from our repository homepage.
You can choose to work on the code from this copy (in git branches), in which case you may occasionally need to delete your savegames if you add classes to the kod code which are not present in other branches. You can avoid this issue by deleting all instances of the new class from the server admin window before saving and switching branches. This will be covered further in a future guide.
Alternatively, you can copy the repository to a separate location (eg. c:\m59source) and work on the codebase from there, copying in/out changes as necessary. You may find it easier, after you gain experience, to work from the repo tracked by GitHub.
Set your GitHub editor
You might want to change your GitHub text editor to something more user-friendly such as Notepad++. You will eventually need to use this editor to do more complicated things from the command line. This Stack Overflow answer gives a great summary of how to set up Notepad++ as your GitHub editor.
Backing up and submitting changes
When you have finished working on a particular feature, or if you just want to back up some changes, first open up GitHub and create a new branch by clicking on “master” at the top of the window (see previous pic of the GitHub graphical interface). Note that it is very important never to make changes on the master branch, as this is the branch from which you should create other branches and it should always be identical to the upstream (Daenks’ repo) master branch. Write in a name for your branch and click the “Create branchname” text. This process is equivalent to running the command
git checkout -b branchname
in Git Shell. Copy in your files (or start making your changes) and when you are done, write in a short commit title and a more descriptive message underneath it and click the button underneath to make the commit.
This is equivalent to running the commands:
git add . and git commit
After you do this, you can then click Publish in the top-right corner of the GitHub window to push the change to your web GitHub repository, which is equivalent to running git push in the shell. When you make future changes to the same branch, the Publish will change to Sync if you’ve pushed the branch to the web GitHub repo. Note that you can create branches from other branches than master, if you wish to duplicate their content.
Updating your local repository
Whenever we push an update to the 103 repo master, you will need to update your local and GitHub repositories to obtain the changes. This is easiest done from Git Shell in the following manner:
We update fairly frequently and push small fixes to our repository in-between updates, so it is a good idea to check often that your master is up to date with the 103 repository master.
Updating your existing branches
If you’ve been working on something and we update, you should also apply that update to any existing branches you have (especially if you are using them in pull requests). This is done using the git rebase command in Git Shell.
Unfortunately there can often be “merge conflicts” where you’ve changed the same lines in your branch as we have in our update, at which point you will have to resolve the merge conflict. The following images describe a particularly bad conflict where several binary files (in this case, the .roo room files) and a text file conflict.
In the first image, we start the rebase with git rebase master and find there is immediately a conflict. In this case we want to keep the modified file, which we can do using git checkout --theirs /path/filename (using --ours instead of --theirs would keep the copy of the file that is in master, instead of the branch we’re rebasing). Add the file using git add . and continue the rebase using git rebase --continue. Use git rebase --abort if you wish to reverse the rebase.
We have another conflict, this time with a text file instead of a binary (you can see the resolution of multiple conflicts at the top of the screen). For this type of conflict we edit the file to contain what information we need for our branch (often integrating the branch changes on top of those coming in from master) and add the file using git add . as before.
When the rebase is finished, push to GitHub if necessary using git push -f.
This is probably as complicated a rebase as you’re likely to see, unless you have very old branches that haven’t been updated with multiple line conflicts in large files. You can read more about merge and rebase conflicts here. Git rebase can also be used to combine several commits into one, using git rebase -i master and selecting fixup for the commits you wish to combine into the commits above them.
Making a Pull Request
Pull requests are the method by which contributors submit their changes for testing and inclusion to the 103 master. To make a pull request first make your branch, commit changes and Publish it as described above, then go to Daenks’ repo and you should see a new row at the top of the code listing:
Click on the big green button to start the pull request procedure. You can also go to the “Pull requests” section on the right-hand side and use the New Pull Request button there (you will have to fill out the branch details if you do it that way).
Either way, you will get to this screen:
where you can change which branch you’re submitting if you wish, and also where you need to leave a pull request name and description. The description should ideally give enough information for us to know why you made the change and what it does, why it is necessary and any remaining issues with it.
Accidental changes to master/revert commit
The last topic to cover is how to remove commits and fix accidental changes made to the master branch. As noted before, this branch should never be modified as you need it identical to the upstream master. If this does happen you have several options:
- If you haven’t already committed the files, you can usually create a new branch from master and commit the files there (problem solved).
- You tried 1 and you couldn’t change branches, or you’ve already committed. If you can’t change branches, just commit the change and skip to the solution. If you want to save the changes, create a new branch off master (which will carry your change with it) and then go back to the master branch.
- You have saved the change you want, or you just want to get rid of the change completely.
To get rid of a commit, from Git Shell, run the command:
git reset --hard head^1
This will delete the last commit on that branch, so if your master branch was a commit ahead, it would now be in sync with the upstream master. Don’t use this one too carelessly, always double check that you’re sure you want to erase the commit.
This should take care of almost everything you need to do to maintain your local repo and submit changes to the codebase. If you have any further questions, you can post on the forums or ask in our IRC channel #Meridian59 on irc.esper.net (or click the Chat board on the forums to be directed there).
-Delerium