Difference between revisions of "Mercurial Repository"

From Hero of Allacrost Wiki
Jump to: navigation, search
(Created page as a primer to working with our new mercurial repository on BitBucket)
 
(Updated page to recommend no longer using personal/forked repositories and instead use properly named branches off the main repository.)
Line 1: Line 1:
This page contains information about using Allacrost's Mercurial repository on [http://bitbucket.org BitBucket]. This information is for developers or anyone else seeking to make changes to the code, scripts, or other files contained within the repository.
+
This page contains information about using Allacrost's Mercurial repository on [http://bitbucket.org BitBucket]. This information is for developers and anyone else seeking to make changes to the files contained within the repository.
  
 
== Learning Mercurial ==
 
== Learning Mercurial ==
  
Mercurial (abbreviated as 'hg', the atomic symbol for the element mercury), is a [https://en.wikipedia.org/wiki/Distributed_revision_control 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.
+
Mercurial (abbreviated as 'hg', the atomic symbol for the element mercury), is a [https://en.wikipedia.org/wiki/Distributed_revision_control 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.
 +
 
 +
* [http://hgbook.red-bean.com/read/migrating-to-mercurial.html#id442397 SVN Command Equivalents] - If you are familiar with subversion/SVN, this table will help you quickly get up to speed.
 +
* [http://hgbook.red-bean.com/read/ 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.
 +
* [https://confluence.atlassian.com/display/BITBUCKET/Bitbucket+Documentation+Home BitBucket Documentation Home] - Contains information on how to use Mercurial together with BitBucket
 +
 
  
 
Allacrost hosts our online mercurial repositories on BitBucket. For developers, there are three repositories you will work with.
 
Allacrost hosts our online mercurial repositories on BitBucket. For developers, there are three repositories you will work with.
Line 9: Line 14:
 
# Your '''personal''' repository online at BitBucket. You upload the commits you made to your local repository with <tt>hg push</tt>. The URL for your page depends on your BitBucket username. For example, user 'rootslinux' has their personal repository at: https://bitbucket.org/rootslinux/allacrost
 
# Your '''personal''' repository online at BitBucket. You upload the commits you made to your local repository with <tt>hg push</tt>. 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
 
# 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.
 
 
* [http://hgbook.red-bean.com/read/migrating-to-mercurial.html#id442397 SVN Command Equivalents] - If you are familiar with subversion/SVN, this table will help you quickly get up to speed.
 
* [http://hgbook.red-bean.com/read/ 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.
 
* [https://confluence.atlassian.com/display/BITBUCKET/Bitbucket+Documentation+Home BitBucket Documentation Home] - Contains information on how to use Mercurial together with BitBucket
 
  
 
== Getting Started ==
 
== Getting Started ==
  
If you're new to Allacrost development, follow the steps below to get everything setup.
+
Follow the steps below to get the latest copy of Mercurial on your system.
  
 
* 1. Install Mercurial Client Software
 
* 1. Install Mercurial Client Software
Line 25: Line 23:
  
 
* 2. Create an Account on BitBucket
 
* 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.
+
Go to https://bitbucket.org/ 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 https://bitbucket.org/allacrost/allacrost/ 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 <tt>user/roots</tt> and make all of your changes there. You can make a new branch from the default by running the command <tt>hg checkout {your branch name here}</tt>.
 +
 
 +
=== 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.
  
* 3. Create a Fork of the Central Repository
+
* 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.
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.
+
* 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.
  
* 4. Create a Clone of your Personal Repository
+
But there are also some reasons why you might want to use a forked 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.
+
 
 +
* 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.
 +
 
 +
# Navigate to https://bitbucket.org/allacrost/allacrost and click "Fork" on the left side of the page.  
 +
# 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.
 +
# 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 ==
 
== Development Process ==
  
TODO: mention about branches, improve this section, etc.
+
Before you begin making changes, make sure you are using the proper branch to do so. You can check this by running <tt>hg branch</tt> to print the name of the branch currently checked out. To switch to another branch (use <tt>hg update branchname</tt>. 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.
  
* 1. Make changes to your local repository (<tt>hg commit</tt>)
+
 
 +
* Make changes to your local repository (<tt>hg commit</tt>)
 
Be sure to include a short commit message with all commits (<tt>hg commit -m "Improved pathfinding logic"</tt>). After doing this, the changes will be committed to your local repository.
 
Be sure to include a short commit message with all commits (<tt>hg commit -m "Improved pathfinding logic"</tt>). After doing this, the changes will be committed to your local repository.
  
* 2. Push your changes to your personal repository (<tt>hg push</tt>)
+
* Push your changes to the mainrepository (<tt>hg push</tt>)
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.
+
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 <tt>hg commit</tt> and <tt>hg push</tt>
 +
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 <tt>hg pull</tt>
 +
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.
  
* 3. Submit a pull request (Click 'Create Pull Request' at your personal repository page).
+
* Merge the latest version of the default branch into your user branch with <tt>hg merge</tt>
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.
+
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 ==
 
== 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.
+
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 central repository that does not compile or has serious bugs that prevent the game from running.
+
* 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: <tt>user/username</tt> are personal branches and <tt>feature/featurename</tt> 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 [http://www.allacrost.org forums] first to make sure they approve of what you are planning to do.
 
* 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 [http://www.allacrost.org 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.
+
* 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

Revision as of 04:01, 5 October 2018

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.


Allacrost hosts our online mercurial repositories on BitBucket. For developers, there are three repositories you will work with.

  1. Your local repository on your development machine. You directly work with this repository and make commits here using hg commit
  2. 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
  3. 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

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 https://bitbucket.org/ 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 https://bitbucket.org/allacrost/allacrost/ 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 https://bitbucket.org/allacrost/allacrost 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