This page contains information about using Allacrost's Mercurial repository on BitBucket. This information is for developers or anyone else seeking to make changes to the code, scripts, or other files contained within the repository.
Mercurial (abbreviated as 'hg', the atomic symbol for the element mercury), is a DVCS similar to Git. What this means is that every user has their own unique copy of the main repository that they can work with, instead of having all developers making changes to the same central repository, a developer works within their own repository, then later merges their changes to the main repository when they are ready to share their changes.
Allacrost hosts our online mercurial repositories on BitBucket. For developers, there are three repositories you will work with.
- Your local repository on your development machine. You directly work with this repository and make commits here using hg commit
- Your personal repository online at BitBucket. You upload the commits you made to your local repository with hg push. The URL for your page depends on your BitBucket username. For example, user 'rootslinux' has their personal repository at: https://bitbucket.org/rootslinux/allacrost
- The central repository online at BitBucket. You merge changes in your personal repository here by submitting a pull request on the central repository's home page. The URL for this page is: https://bitbucket.org/allacrost/allacrost
If you aren't familiar with Mercurial, there are several resources online to help you learn. A few are below to help you start.
- SVN Command Equivalents - If you are familiar with subversion/SVN, this table will help you quickly get up to speed.
- Mercurial: The Definitive Guide - An online book that goes into great detail. Good as a reference, but has more information than you probably need to know.
- BitBucket Documentation Home - Contains information on how to use Mercurial together with BitBucket
If you're new to Allacrost development, follow the steps below to get everything setup.
- 1. Install Mercurial Client Software
Linux systems should have a local mercurial package (usually called 'hg') available to install on their system that provides command-line tools for working with mercurial. TortoiseHg is a GUI front-end for mercurial primarily for Windows, but also available on OS X.
- 2. Create an Account on BitBucket
Go to https://bitbucket.org/ and make a user account. If you already have an account, you can skip this step if you would like to do Allacrost development with it.
- 3. Create a Fork of the Central Repository
After logging in to BitBucket, go to https://bitbucket.org/allacrost/allacrost and click "Fork" on the left side of the page. This will bring you to a simple form where you can create a copy of the central repository for your user account. This will be your personal repository online at BitBucket.
- 4. Create a Clone of your Personal Repository
On your new personal repository page, click "Clone" on the left side of the page. This will give you the command and instructions you need to clone your personal repository to your local system. After completing the clone on your system, you will now have your local repository available and can begin making commits to it.
TODO: mention about branches, improve this section, etc.
- 1. Make changes to your local repository (hg commit)
Be sure to include a short commit message with all commits (hg commit -m "Improved pathfinding logic"). After doing this, the changes will be committed to your local repository.
- 2. Push your changes to your personal repository (hg push)
A push command will grab all commits you've made to your local repository and publish them online to your personal repository on BitBucket. At this point, others can see the changes you've made in your repository and you can ask for feedback if desired.
- 3. Submit a pull request (Click 'Create Pull Request' at your personal repository page).
Your changes will need to be reviewed and accepted by a senior developer in order for your changes to be pulled into the central repository. They may also deny your pull request, or request a change before accepting them.
Mercurial/BitBucket Usage Policies
We have a few policies for developers to follow in order to avoid problems. These policies apply to any changes you are submitting to the central repository via a pull request. You are free to do whatever you like with your local and personal repositories.
- Do not submit code to the central repository that does not compile or has serious bugs that prevent the game from running.
- If you are planning to add, remove, or rename a file or directory, it's a good idea to mention it to developers on the forums first to make sure they approve of what you are planning to do.
- If you make changes that require an update to the project build files (ex: adding a new source file), you are responsible for updating the build file for the system you are doing your development on only. In your change notes, you should indicate that other project files need to be updated to reflect these changes.