1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.
5/5, 2 ratings

How to Manage a Shard's Code with GitHub and the Command Line

Summary of the tutorial

Explains a step-by-step process for ensuring that your shard's code can be easily maintained with the latest updates from ServUO while retaining your own customizations. Assumes that you are using GitHub and the Git command line tools, and that your shard's code will be public (or that you pay a GitHub subscription fee to keep your repository private).


In this post I will outline the steps required to use GitHub and the git command line tools to create a custom code base for your shard that can be kept up to date with the ServUO codebase as it is updated and allows you to contribute back any bug fixes or feature additions at the same time.

Initial Setup and Workflow for Shard-Specific Features
  1. If you do not have an account at https://github.com/ go create that now.
  2. Now go to the ServUO project page (currently at https://github.com/ServUO/ServUO/)
  3. Click on the "Fork" button. This will create a fork of the ServUO project under your user account.
  4. Rules about the fork:
    1. Never commit to master! The master branch of your fork will track the remote upstream master (ServUO/ServUO) and will be where we pull changes from upstream. It is very important that you never make your own changes to the master branch.
    2. Always branch from master unless you really know what you are doing. This means that before you create any branch in the GitHub interface, the master branch should be selected and displayed in the branch drop-down.
  5. Now create a branch for your shard. As of the time of this writing this is done by opening the branch drop-down and typing in the new name of the branch. Name it something descriptive, like "Ponies Forever Shard".
  6. If you do not have the git software installed, do so now.
    1. For Windows systems, go here: https://git-scm.com/download/win
    2. For Linux systems, use your package manager
      1. For Debian-based systems the command is usually "sudo apt-get install git"
  7. Navigate to a location on your local file system where you would like ServUO to live.
    1. On Linux systems do this in a shell
    2. On Windows do this in an Explorer shell, then right-click in the folder and select "Git Bash Here"
  8. On the main GitHub page of your fork will be a URL ending in .git. Copy that URL.
  9. In the shell execute the command "git clone [the-url]"
    1. This will create a new directory named ServUO
    2. Execute the command "cd ServUO" to enter it
  10. Execute the command "git remote add upstream https://github.com/ServUO/ServUO.git"
    1. This is the configuration needed to update from upstream master later on
  11. Important! Execute the command "git checkout [shard branch]" where [shard branch] is whatever you named the branch to contain your shard-specific code.
    1. If the branch name contains spaces replace them with dashes "-"
    2. This makes it so that all code changes you make are contained within the shard branch and do not touch master
  12. Write code here that is not intended to be pushed to the upstream repository. Things like changing the current expansion and setting the data path are good examples.
  13. Every time you have a tested, working change, commit and push them.
    1. Execute the command "git status" to see all modified files and ensure that it makes sense
    2. Use the command "git add [the-file]" to add the modified files to the commit
    3. Use the command "git commit" to commit the changes to the repository history
    4. Use the command "git push" to push the repository history changes to GitHub
Deploying Shard Code to a Remote Server
  1. Follow the above steps for installing git and cloning the repository on the remote server
  2. Execute the command "git checkout [shard branch]"
  3. Now all of the code is exactly like it was on your development machine when you pushed it. Just start the server!
Updating ServUO Code
  1. Enter the ServUO directory with your shell or Git Bash Here command
  2. Execute the command "git fetch upstream"
    1. This will pull in the entire upstream repository into a local branch named upstream/master
  3. Execute the command "git checkout master"
  4. Execute the command "git merge upstream/master"
    1. So long as you never made any changes while on your own master this will be a fast-forward merge and you will not have to do anything special
  5. Execute the command "git push" to update your remote repository with the new upstream code
  6. Execute the command "git checkout [shard branch]"
  7. Execute the command "git merge master"
    1. This is where the pain happens. If you have modified something on your shard that ServUO has also modified (I'm talking the same line of the same file) then you will get something called a merge conflict.
    2. Resolving merge conflicts is too large a topic for this post. Please refer to this fine article: https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/
  8. After the merge is complete, either with no conflicts or after all conflicts have been resolved and committed, execute the command "git push"
Contributing to ServUO Workflow
If you wish to resolve a defect or contribute a feature to the ServUO codebase, please do so! This project would not be where it is without the involvement of its community. When you identify such a contribution, please use the following workflow.
  1. Create a new branch on GitHub.
    1. Again, make sure the master branch is selected before you create the new branch
    2. Name the new branch something descriptive, like "Fix Mysticism Resist Mechanics" or "Resolve Issue 143"
    3. This new branch will be referred to as the feature branch.
  2. Enter the ServUO directory with your shell or Git Bash Here command
  3. Execute the command "git fetch"
  4. Execute the command "git checkout [feature branch]"
  5. Write code that is intended to be pushed to ServUO and commit it every time you have a working, tested solution.
    1. Use the same commit steps from above
    2. Note that you will be coding against stock ServUO, not your shard's codebase. This is important because the patch needs to work with all servers, not just yours.
  6. When the patch is ready to go to ServUO for testing and merge, open a pull request on GitHub
    1. Refer to this document regarding GitHub's UI: https://help.github.com/articles/creating-a-pull-request/
    2. Important! On the screen that lets you write comments for the pull request it also lists the commits contained within the pull request. Review this list and ensure that only the commits you want are included.
    3. Send the pull request off and it will be reviewed by a core team developer.
  7. I would recommend that you wait for the ServUO team to accept the pull request and let it enter your server's codebase that way. But for the impatient, you can do the following to merge it into your shard's code:
    1. "git checkout [shard branch]"
    2. "git merge [feature branch]"
    3. "git push"
Cleaning Up Old Branches
After a pull request has been merged into the ServUO master the branch containing the commits is no longer needed. Here are the steps for cleaning up old branches.
  1. Delete the branch on GitHub by following these steps: https://github.com/blog/1377-create-and-delete-branches
  2. Enter the ServUO directory with your shell or Git Bash Here command
  3. Execute the command "git fetch -p"
Please let me know if there are any other related topics you would like explained.