Developers/Git workflow

Arcavias is hosted on Github which uses the "git" version control system to keep track of changes. If you would like to contribute to the Arcavias code base, this page contains a step by step description of what you have to do.

Create a Github account
First of all, you have to register yourself at Github. This is totally free of charge and is necessary to be able to create your own git repositories on Github or fork existing repositories like the Arcavias one. Please create an account before proceeding to the next step.

Fork the Arcavias repository
After you've signed up, login into your account at Github and go the Arcavias page. You can browse the source code at this stage and the next step is to fork the Arcavias repository. Creating a fork clones the existing repository and creates a new one for you. In this repository, you will be able to make changes. To start the fork process, press the "Fork" button in the upper right corner.

Get a local version of your fork
You can now start to edit files directly in you fork but for bigger changes, creating a local version and working with your favorite editor is much more efficient. This is done by creating a clone of your repository on Github using the git command line tool:

git clone https://github.com/your-account/arcavias-core.git arcavias-core

Please replace "your-account" with your account name before executing the command. After the command has finisched its work, a clone of the complete repository will be available in the "arcavias-core" directory on your local hard disk.

Prepare automatic builds (optional)
To be sure that your changes doesn't break existing tests, you can use the Travis-ci build service to automatically test them on every push to your fork.

To get started with Travis CI, sign in through GitHub by following the Sign In link at the top of the Travis-ci website. GitHub will ask you for granting read- and write access. Travis CI needs write access for setting up service hooks for your repositories when you request it, but it won't touch anything else.

Once you're signed in go to your profile page on Travic-ci. You'll see a list of your repositories. Flip the on/off switch for each repository that you want to hook up on Travis CI. Then visit the GitHub service hooks page for that project and paste your GitHub username and Travis token into the settings for the Travis service if it is not already pre-filled.

That's it! Now every push to the repository will start a build on Travis-ci. You can view the output of the tests on

https://travis-ci.org/your-account/arcavias-core

when you replace "your-account" with the name of your Github account. The test builds for the Aracavias main repository are available here. Before we will merge your changes to the main repository, we will wait for the result of the Travis-ci build.

Update the repository
After the steps to create a local repository, you can start changing the code or adding new features. An important thing before you do any changes is to update your local repository because in the meantime other developers may have implemented features or corrected bugs as well. If you are using an outdated code base chances are high that you will get conflicts if someone else changed the same lines of code or you are hunting a bug that was already fixed. The time for both is better spent for other things for sure :-)

To update your code base prior to every change enter the following commands on the command line:

git pull git pull https://github.com/Arcavias/arcavias-core.git

The line consists of two git commands: The first one fetches all updates from your fork and merges them into your local repository while the second one does the same for all changes available from the main Arcavias repository. Especially the second one is extremely important as it's very likely that someone else has integrated a change into the main repository.

Commit changes made
Every time you've finished a change (which may consist of a series of small changes that belong together) you should commit your changes. At first, you have to tell git that it should add the changes to the next commit. This is done by using

git status git add 

Afterwards, you can commit all added files by using

git commit -m " "

on the command line. Please replace the message text with an english description of what your change set will do.

Transfer changes to Github
All your changes are still on your local machine and you would like to get them integrated into the main repository for sure. Make sure that the tests are still working and the coding guidlines are met. The first step to start integration is to push your changes to your own Github repository:

git push

This transfers all changes and you should see them in the code browser of your own repository on Github.

Start a pull request
To get your changes into the Arcaivas core, you have to tell us that you want to get your code into the main repository. You have to be logged into the Github website and be on the main page of your fork. Right of the name of your fork (below the top toolbar) there's a button named "Pull request". Follow the steps the create such a pull request and we will get notified about.

Maybe we find points to discuss about in your code. In this case we add our comments to the code in question. After we think that the code is good enough to be integrated, we will merge it into the Arcavias repository. That's it and you can start to implement your next feature :-)

Create a remote branch
First create a local branch:

git checkout -b

transfer local branch to server

git push origin :

Or you can use:

git push -u  

instead, so that a subsequent git pull will know what to do.

Delete a remote branch
git push origin --delete

Getting a remote branch
git remote update

Gets all branches

git checkout -b  /

Makes a new local branch which tracks the remote branch.

Git troubleshooting
In case you encounter the following error message: fatal: You don't exist. Go away!

Please update your global config git config --global user.name "John Doe" git config --global user.email john.doe@metaways.de