GitHub Access

Table of Contents Github access Access to the repository as a user Developing using git People able to merge pull requests in the main MH branch Creating a pull request

Github access

In an attempt to ease the process of contributing code and patches to the MisterHouse code base, a git repo has been setup in November 2012.

The repository lives here and can be cloned to your own Github account for code development.

Advantages of the github account compared to the SVN repository include:

• Easy diffs between various versions and branches
• Invites people to actually contribute code back to the main code tree when they develop some local changes (through pull requests)
• Inherent availability of tgz files when creating a tag for people that just want to download and use such a version

It is currently unclear if the git repository will become the main development base in the future, as there is not clear decision made by the MisterHouse developers. Over the last years, the idea of creating a github repository for MisterHouse has been suggested a few times, but it never actually happened. I (Lieven) decided to try it out. IMHO everything that makes contributing code easier can help bringing new life to MisterHouse. Of course, if we see that nobody actually uses the git repo , then we can call it a failed experiment at a certain point in time and continue using the SVN repository. I will from my side in the mean time port SVN commits to the git repo until at least the end of 2012. This way the only risk of fragmentation (which some developers fear) is when commits that are made to git are not backported to the SVN repo.

Access to the repository as a user

To get the source code from the git repository, please follow these instructions.

Developing using git

A quick-start guide into using git.

1. Create a github account an prepare your environment for committing. This means that you will define your username and email address that will be used when you commit changes. See https://help.github.com/articles/set-up-git for details. The most handy way to interface to git is using SSH keys.
2. Fork the misterhouse repo I created (single button click in the right upper corner here: https://github.com/hollie/misterhouse)
3. Clone your fork to your local machine with: git clone git://github.com/tmaclean/misterhouse.git This automatically sets the origin to your repository
4. Create a branch where you will develop your change (cd misterhouse; git checkout -b feature_x)
5. Develop, test
6. Stage the files you want to commit (this means telling git what files you will commit in the next step): git stage <files></files>
7. Commit. This will commit the changes to your local repo: git commit -m "Descriptive message here"
8. Push your changes to your github repository: git push origin feature_x
9. Create the pull request by navigating to your github web page, clicking on the commit, and then click the 'pull request' button. More details, see here: https://help.github.com/articles/using-pull-requests

Now I hear you thinking: "Wow, nine step, and you told us it would be more easy than using SVN man..." Well, in practice, when you already have the repo forked and setup on your computer, adding a change is as easy as iterating through steps 4 - 9:

• $> git checkout -b feature_x
• add/modify code
• $> git stage <files></files>
• $> git commit -m <descriptive></descriptive>
• $> git push origin feature_x
• create the pull request

Moreover, and not immediately visible from the steps I described, integrating the change to the master branch is easy and can even be done through the web interface by the people that volunteer to merge back changes proped by the other developers. A list of people that are able and willing to do so is listed below.

Finally, a general quick overview of basic git usage can be found here: http://rogerdudler.github.com/git-guide/

People able to merge pull requests in the main MH branch

When developing an open source project, it is important to not have a single person being responsible for maintaining the main code branch. On the git account, this is done first of all inherently by the working principle of git. If I ever run under a bus, anybody else willg to do so can fork the main repo and change the link at the top of this page to his/her user account, thereby taking over the repository. Moreover, to avoid that changes don't make it to the main branch because of me being on an extended vacation to the Bahamas, other volunteers/developers/enthousiasts are permitted collaborator access to the repository on my user account. Currently, the list of people who are able to make changes to the repo are:

• hollie (Lieven Hollevoet)
• marcmerlin (Marc Merlin)

Just send a request to the MisterHouse mailing list with the reason why you'd like to be added and we'll grant you access.

Creating a pull request

a.k.a. contributing code.

So, git is a different beast compared to SVN. The reasoning behind going for git were already listed. This section shows you how to contribute code.

1. Create your account on github.comand log in.
2. Through the web interface, fork the MisterHouse repository from here
3. Now you have your own fork that you can use to work on. Clone it to your working machine: git clone git@github.com:/misterhouse.git
4. You now have a copy of the master branch of your fork on your computer. Prepare it to start implementing changes by creating a branch to work in. It is considered bad practice in git to directly work on the master branch because this complicates the exchange of the code you added or changed. Suppose you make a change and somebody else want to continue working on it. If the change is made in a branch that person can pull your changes into his/her repo and contribute to your work. If you made various changes to your master branch then it is hard to determine what changes need to be pulled in to help you further. Making the branch to work on is easy 'git branch feature_xyz' followed by 'git checkout feature xyz'.
5. Work on the code, test
6. Stage: git stage <files></files>
7. Commit: git commit. In the editor that appears, enter a first line with a short description of the change, then an empty line and then a longer description. This will be useful when creating the pull request later.
8. Publish the branch with the change: git push origin feature_xyz
9. Then in the web interface navigate to the commit, click the 'create pull request' button and the next screen will be auto-filled in with the info you put in the commit message. Title will be the first line of the commit, body will be the content you added to the commit message after the empty line.