Resource icon

Using GitHub to Manage a Shard's Custom Code and Contribute to ServUO

Overview Discussion
Norman Lancaster

Norman Lancaster

Member
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.

Thanks!
 
Norman Lancaster said:
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.

Thanks!
Click to expand...

Ahh! I love when people use branch management tools effectively! Puts a smile on my face. It makes it so easy to handle having more than two developers constantly adding updates.

Cheers on the guide for people! Hopefully everyone gets used to this process!
Also Git-Scm is awesome and so easy to use.
 
Only problem I see with this method is that your shard will be public since you are forking from a public repo.
 
I do not personally find that to be a problem. I think what holds a community together is not expressed in code. But I understand others see things differently. You can use these same steps to fork ServUO into a private git repository, but you'll have to replace the GitHub UI with git commands or another UI.
 
Norman Lancaster said:
I do not personally find that to be a problem. I think what holds a community together is not expressed in code. But I understand others see things differently. You can use these same steps to fork ServUO into a private git repository, but you'll have to replace the GitHub UI with git commands or another UI.
Click to expand...

Please don't take me wrong, your post was awesome!

Just pointing out the limitation because I know many people will care.
 
This is awesome. I only have basic Git knowledge, enough to have made my own fork and to know how to push changes and submit pull requests (enough for my needs to just have a shard and submit bug fixes/submissions to servuo repo) but many people don't even have that and this post will certainly help them.

I'd also like to note that it is possible to do the steps in this tutorial through a nice graphical interface rather than command line with the use of SourceTree. Obviously if you want advanced, granular control over your repository you will want to learn the command line functions but if you're just looking for what you need to setup ServUO and maybe help the project by submitting bug fixes everything you need you can do through SourceTree (or another Git program with a GUI). There's buttons for everything in this tutorial in SourceTree -- you can find SourceTree here: https://www.sourcetreeapp.com/

Anyways, this really needed to be done so I commend you for taking the time to submit this resource!
 
Thanks for the feedback! Unfortunately I do not know any GUI tools for git. This has been an issue at work too. Part of my job is teaching others how to use git. But I need to learn the GUIs we have so I can help the folks that don't like the command line.
 
I'll post a guide for git gui tonight after work.
It's really easy and is absolutely necessary for teams larger than 2 working on something.
 
TortoiseSVN and TortoiseGIT are great Windows GUI's for their respective repository systems.

You don't need any knowledge of shell commands to use them.

WinMerge will also integrate in to Tortoise* which is extremely useful for viewing repository logs and differences.
 
For the record, SourceTree by Atlassian is also amazing. Toriad turned me on to it back when he was around.
 
You clone the repository. Then "checkout" the branch. This will prevent anything from changing on the master. Master should always be a copy of the upstream, at least in the workflow I like to use :)
 
I followed all the steps above ended up with a copy of everything inside my folder named servuo didnt actually make changes so im confused as to where i messed up or if its supposed to do such...
 
You must log in or register to reply here.

Active Shards

Donations

Total amount
$0.00
Goal
$1,000.00
View
Back