Mercurial Repository

From Hero of Allacrost Wiki
Jump to: navigation, search

This page contains information about using Allacrost's Mercurial repository on BitBucket. This information is for developers and anyone else seeking to make changes to the files contained within the repository.

Learning Mercurial

Mercurial (abbreviated as 'hg', the atomic symbol for the element mercury), is a DVCS similar to Git. The main repository is stored on the Bitbucket servers, and users can clone a local copy of this repository on their personal computers. If you aren't familiar with Mercurial, there are several resources online to help you learn. A few are below to help you start.

Getting Started

Follow the steps below to get the latest copy of Mercurial on your system.

  • 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 and make a user account. You can skip this step if you already have an account and don't mind using it for Allacrost development.

  • 3. Create a Clone of the repository

Navigate to in your web browser and then click the Clone button located on the top right of the page. This will give you the command and instructions you need to clone your personal repository to your local system. There are a lot of files so it may take a few minutes to download the repository. After the cloning is complete, you will now have your local repository available and can begin modifying files, compiling the game, and committing changes.

  • 4. Create a personal user branch

The main repository will not accept any changes made directly to the default branch. Before you start making any changes, create a personal branch for yourself to hold all of your changes. Whatever alias you've chosen to use with this project should be what your branch is named, in all lower-case characters. For example, if your user name on the forums, Discord, etc is "Roots" create a branch named user/roots and make all of your changes there. You can make a new branch from the default by running the command hg checkout {your branch name here}.

Using a forked repository

If you so desire, you have the option to have a copy of the main repository tied to your personal account (called a fork) and you can clone this fork repository to your system. This is not recommended for most users for a few reasons given below.

  • Changes you make to your forked repository won't be reported automatically to our Discord channel, making it more difficult for others to know when you've recently made a change.
  • You'll have to continually pull in changes made to the main repository to your fork, which isn't difficult but makes the development process more tedious.
  • For another user to test out your changes before they are merged into the main repository, they'd need to clone your fork (in addition to the clone of the main repository on their systems), which is time consuming and tedious to do.

But there are also some reasons why you might want to use a forked repository.

  • You intend to use Allacrost as a starting point to build your own game, engine, or editor project.
  • You want complete control over how you name and manage the your repository and don't mind dealing with merging your changes back into the main repository.
  • You want to make radical changes to the software without requiring any sort of approval from others.

If you're unsure if you should use a forked repository or not, hop on our Discord channel and ask. Doing your development on the main repository requires following a very small number of rules, which are explained in the section that follows. If you do decide to setup a forked repository, follow the steps below to create it and clone it to your local system.

  1. Navigate to and click "Fork" on the left side of the page.
  2. Doing so will bring you to a simple form where you can create a copy of the main repository to your user account. This will be your personal forked repository online at BitBucket.
  3. After the fork has been created, navigate to the main page of the repository (you should see it listed under your account if you aren't brought there already). Click the Clone button and follow the same instructions as you would for cloning the main repository.

Development Process

Before you begin making changes, make sure you are using the proper branch to do so. You can check this by running hg branch to print the name of the branch currently checked out. To switch to another branch (use hg update branchname. Branch names should either begin with user/ if it is a personal user's branch, or feature/ if this is a branch for a specific change under development. Most of the time it is recommended that you just do your development within your user branch. Use feature branches when: you are working on multiple sets of changes concurrently, or you are collaborating on a specific large set of changes with another person.

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

  • Push your changes to the mainrepository (hg push)

A push command will grab all commits you've made to your local repository and publish them online to the main 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. An update notice will automatically be posted in the project Discord channel alerting others that the changes are now available.

  • Submit a pull request to the default branch (Navigate your browser to the main repository, select your branch, then click 'Create Pull Request').

Your changes will need to be reviewed and accepted by a senior developer in order for your changes to be pulled into the default branch of the main repoistory. They may also deny your pull request, or request further changes before accepting them.

  • Add additional changes to a pull request with hg commit and hg push

If you need to make additional changes to a pull request, simply update the source branch. After pushing the additional changes the pull request will automatically be updated to include them.

  • Pull the latest changes down from the main repository with hg pull

Note that the default branch is where changes get pulled into, thus the default branch on your local clone will contain the latest approved changes.

  • Merge the latest version of the default branch into your user branch with hg merge

Merging will put the latest changes from the default branch into your branch. Note that you should never attempt a merge where the default branch is the destination branch (it should only ever be a merge source branch). Doing this will cause you headaches when your local default branch no longer shows the same set of changes in the main repository.

Mercurial/BitBucket Usage Policies

We have a few policies for developers to follow in order to avoid problems and mitigate potentially frustrating situations.

  • Do not submit code to the default branch that does not compile or has serious bugs that prevent the game from running.
  • Follow and respect the branch naming schemes: user/username are personal branches and feature/featurename for any
  • 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. You should let others know (either on the forums or Discord) that other project files need to be updated to reflect these new changes.
  • Never close a user branch after a merge request is accepted