EMLab and Github

Introduction

This document describes the workflow of the EMLab power generation model and github. For more information on github: http://git-scm.com/book

Structure

Github works with repositories, branches and tags. Our central repository is called EMLab, which is located here: https://github.com/EMLab/emlab. Each contributor is a user on Github and has/creates its own repositories for the projects they work on. That's how users typically work on their own repositories and commit finished code parts to the main repository. This keeps the process and result clean.

Within each of the repositories, there are branches. There are three different types of branches. The current stable version of the model is in master. New versions can be merged into this branch when the version in the develop branch is stable. The develop branch contains all finished new features. New features (parts of code, modules, projects) are developed in feature branches.

• master
• develop
• feature/...

There are also tags, that are bookmarks for particular revisions used, for instance in reports and papers. Tags are typically created from the master branch.

• tag/...

Getting started & Basic Workflow

Getting started

1. Make a private account on Github.
2. If you don't have a set-up Git installation, follow the instructions here.
3. Fork from the main repository in your own private repository, by clicking on Fork in the right hand top corner.
4. Clone to your own computer by running git clone --recursive https://github.com/YourAccount/emlab-generation.git The recursive automatically downloads the included AgentSpring submodule. In case this fails and your AgentSpring directory is empty, run: git submodule init and than git submodule update
5. Enter the emlab-generation folder (e.g. cd ~/emlab-generation).
6. Add the original EMLab repository as a second remote git remote add EMLab https://github.com/EMLab/emlab-generation.git
7. Run mvn clean install
8. If you are running Linux adapt the bash script configurations file, by running cp TEMPLATE_emlabConfig.cfg emlabConfig.cfg in the shellscripts folder, and than adapting emlabConfig.cfg to your system.

Adding new features

• Create a new branch called feature/YOURFEATURE based on the EMLab/develop branch
• Work in the new branch on your private repository until you have a working, tested version.
• Merge new changes from the EMLab/develop branch into your feature branch. Test again whether these changes are compatible.
• Push the branch to your private repository, by checking the branch out (git co feature/YOURFEATURE) and pushing it to your personal repository git push origin feature/YOURFEATURE
• Place a pull request to the EMlab/develop branch using Github

For small changes

• Merge new changes from the EMLab/develop branch into your develop branch.
• Work in the develop branch on your private repository until you have a working, tested version.
• Place a pull request to the EMlab/develop branch

Using Github in SpringSource

We develop the model in SpringSource (http://www.springsource.org/sts), which is a version of Eclipse, bundled with plug-ins. The whole process described above can be executed within SpringSource. Following you can find an initial set-up description:

Initial set-up

1. Set-up an initial clone as described in the steps of Getting started
2. Open SpringSource, open the Dashboard
3. Choose Window → Preferences → Team → Git → Configuration to adapt your git settings (more detailed description can be found here). Set your name equal to your Github user name and the email address to the address used on Github.
4. Right-click in the package explore -> Import -> Maven -> Existing Maven projects.
5. Choose YourPath/emlab-generation/emlab-generation as a root folder, the pom.xml should be automatically found.
6. Right click on emlab-generation->Team->Share Project . Choose git, select the "Use or create repository in the parent folder of the project." and finish.
7. Choose Project -> Properties from the menu bar
   • Choose Java Build path from the left column: Inside the dialogue choose the tab Libraries. Choose JRE and click on edit. Click on alternate JRE and choose java-7-oracle
   • Click on Order and Export tab. Move Maven Dependencies above the JRE Systems Library.
   • In the left column search for Code Templates. Choose from the menu Project → Properties.Enable "Project specific settings." Import and choose the file codetemplates.xml in the emlab-generation/emlab-generation folder. Edit "Types" so that instead of author ${user}, you use your Github user account, or your real name. Check the box "Automatically add comments ..." on the bottom of the dialogue
   • In the left column search for "Save Actions". Enable "Project specific settings." Enable the check boxes "Perform the selected actions on save", "Format source code", "Format all lines", "Organize imports."
8. Go into the src/test/java folder right click on a test class -> Run As -> JUnit test. If the test doesn't fail, the setup of STS should be complete.