-
Notifications
You must be signed in to change notification settings - Fork 29
Contributing Code
We welcome contributions from anyone who wants to make Lacuna Expanse a better game for the whole community. Contributions can be as simple as correcting spelling mistakes in messages or as complicated as adding whole new game play features. All we ask is that you follow a few simple guidelines to make it easy for us to accept your changes.
If you want to contribute code to the Lacuna-Server-Open (ls-open) repository, these are the steps that you will need to follow.
- Create your own fork of ls-open, preferably on github
- Clone your repository to your local machine (where you will make the changes, and of course create tests for your code)
- Commit your changes and push them to your github repository.
- Issue a pull request to us to review and accept your changes.
That's fairly straightforward, but the devil is in the detail as they say!
This process is described at https://help.github.com/articles/fork-a-repo Please do this, and be sure you are familiar with how to clone it, make local changes, push them to your forked repository. You might also want to refer to some general git documents such as:-
To make this easier to understand, I will follow through a few simple scenarios with step by step instructions.
- Fixing a bug
- Helping to test and fix a new release
- Creating a big new game feature.
First of all we should only be fixing bugs in the production version of ls-open that have a corresponding Issue raised. This is so that we can link the code changes back to a bug request. So, if you find a bug that does not have an issue raised, please raise one at https://github.com/plainblack/Lacuna-Server-Open/issues
Please read the guidelines on how to submit a bug (TO BE DEFINED).
You should make sure that your forked repository is up-to-date with respect to the plainblack one. To do this refer to the document at https://help.github.com/articles/fork-a-repo, specifically the 'Pull in upstream changes'. If you don't do this, and you are using an old copy of the code, then your code may be rejected because it cannot be merged.
For bug fixes you should create a new branch off master and name the branch based on it's bug number together with a few words to help identify it. e.g. bug_2_missing_plans
$ git checkout master
$ git checkout -b bug_2_missing_plans
Carry out your changes, commit them as normal on your local repository and push them to your github repository
$ git push origin bug_2_missing_plans
You now need to issue a pull request to plainblack/Lacuna-Server-Open, see https://help.github.com/articles/using-pull-requests for details. Note, for bug fixes you 'base' the pull request from 'master' so there should be no need to change any of the default values. If it is not based on master then click the change commits button.
Congratulations, you have now submitted your first bug patch!
All development on Lacuna-Server-Open takes place on the infinite develop branch. This branch is never closed and just tracks alongside master. When develop has reached a point where everything for the next release has been done then a branch is taken off it to produce a release-branch, e.g. rel-3.0859. From this point, no new features will be added to the release branch, only bug fixes will be done.
To help to test and fix bugs on this branch you need to ensure that your forked github has fetched the latest changes from plainblack/Lacuna-Server-Open and you can start working on the release branch.
When you have made changes on your copy of the release branch you should issue a pull request. In this case however ensure that your pull request is being based on your develop branch.
A big new game feature may take some time to develop. Probably spanning several releases. For this reason it should not be carried out on the develop branch, since this would prevent interim releases. You should make a new feature branch.
You can also make feature branches for smaller pieces of work, as you see fit.
To create a feature branch you should checkout the latest master branch and branch off from there. e.g.
$ git checkout -b big_game_feature
For an example of this have a look at the fleet-action branch, which spanned several months.
You should continue to develop your code, and test it, whilst on your big_game_feature branch.
As you develop your code you will want to make sure that it still works with the latest released version of Lacuna-Server. To do this you will either merge from master or (preferably) rebase your code on top of master after each release.
If you are the only person developing this major new feature then you should periodically rebase your code on top of the current master branch. Rebasing works well because it creates a linear history which will be very easy to merge with the open-source repository once your feature is complete. The downside to rebasing is if you are collaborating with someone else and using a shared public (or semi public) repository.
If you plan on working on a major feature with someone else, then please contact an administrator to discuss it. Instructions on how to proceed will need more careful consideration than can be documented here.
So, we will assume that you are developing your new feature on your laptop with a clone of the open-source repository (pb-ls-open).
$ git clone [email protected]:plainblack/Lacuna-Server-Open.git --origin pb-ls-open
$ cd Lacuna-Server-Open
$ git checkout master
$ git checkout -b my-new-feature
You can now work on you new feature, test it locally, commit your changes.
Assuming there is a new release of Lacuna-Server-Open while you are developing your code, you need to ensure that your code continues to work. For this you need to bring down the changes and apply them to your feature branch.
$ git checkout master
$ git pull --ff-only pb-ls-open master
$ get checkout my-new-feature
$ git rebase master.
You can continue to work on your new feature in this way until you are ready for it to be pulled into the open source code.
I should repeat the warning. Doing a 'rebase' will rewrite the history of your code. It goes something like this.
A---B---E master
\
C---D---F my-new-feature
This might represent your repository immediately after you have done a 'get checkout master'. Your local changes C, D and F on the 'my-new-feature' branch and the change E which was pulled down from the open-source repository.
After you do the rebase command your repository will look like.
A---B---E master
\
C'--D'--F' my-new-feature
You have 'rewritten history'. Your change C which was originally applied to B will now appear as if it was applied to E.
This is a very good way to work if you are working alone, since it keeps a linear history and in fact correcting any conflicts is easier (since any conflicts are generally in smaller chunks).
However if you have previously pushed your my-new-feature to a public repository, and someone else has forked or cloned it, then rewriting history Is A Bad Thing, as we have already said.
So, you have completed your code, you want to submit it to the open-source repository. One final thing you may be asked to do is to rebase it on the develop branch. This is the same process as above.
$ git checkout develop
$ git pull --ff-only pb-ls-open develop
$ git checkout my-new-feature
$ get rebase develop