Skip to content

Contributing

Jump to bottom Edit New page
hollie edited this page Nov 25, 2012 · 8 revisions

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.

Checking out the code from git for installing MisterHouse

Follow this procedure if you just want to get the code from the repository to use it or for testing purposes. If you plan to contribute, please see below.

  • Install git
  • Navigate to the folder where you want to clone the code (a folder will be created by the next command)
  • execute git clone git://github.com/hollie/misterhouse.git
  • The master branch of misterhouse is now cloned in the folder 'misterhouse'
  • If you need a specific branch you can now perform git checkout <branch_name>

Developing using git

A quick-start guide into using git.

  • 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.
  • Fork the misterhouse repo I created (single button click in the right upper corner here: https://github.com/hollie/misterhouse)
  • Clone your fork to your local machine with: git clone git://github.com/<username>/misterhouse.git This automatically sets the origin to your repository
  • Create a branch where you will develop your change (cd misterhouse; git checkout -b feature_x)
  • Develop, test
  • Stage the files you want to commit (this means telling git what files you will commit in the next step): git stage <files>
  • Commit. This will commit the changes to your local repo: git commit -m "Descriptive message here"
  • Push your changes to your github repository: git push origin feature_x
  • 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

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>
$> git commit -m <descriptive message>
$> 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 proposed 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)
jdud (Jim Duda)

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. Even better is contributing a code change through a pull request.

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.

  • Create your account on github.comand log in.
  • Through the web interface, fork the MisterHouse repository from here
  • Now you have your own fork that you can use to work on. Clone it to your working machine: git clone [email protected]:/misterhouse.git 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.
  • Work on the code, test
  • Stage: git stage <files>
  • 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.
  • Publish the branch with the change: git push origin feature_xyz
  • 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.

Undo an invalid merge

It can happen that somebody accidentally accepts a pull request that should not have been accepted. To revert the master to the state before the merge, proceed as follows:

First determine the ID of the commit that is the last correct one. You can do that through the web interface.

Then perform the following commands:

foamy:misterhouse lieven$ git checkout master
Already on 'master'
foamy:misterhouse lieven$ git pull
Already up-to-date.
foamy:misterhouse lieven$ git reset --hard 06f01c3b7fca24bf55449077bd8c6dee0de668ae
HEAD is now at 06f01c3 Add support for CALLERID popup and other basic NOTIFICATIONS.
iMac:misterhouse lieven$ git push -f origin master
Total 0 (delta 0), reused 0 (delta 0)
To [email protected]:hollie/misterhouse.git
 + ff69f1f...06f01c3 master -> master (forced update)

Done!

Cherrypicking a specific commit from other repos/branches

If you don't want to merge a complete branch from a contributor, but you only want to apply a specific commit, proceed as follows. The working assumption is that jduda has made a commit to a branch of his fork, and we want to get that change into master.

We have a clone of hollie/master that is up to date with origin, and we proceed like this. First we determine the SHA ID of the commit we're searching for (e.g. through the web interface). Once we have this we do:

foamy:misterhouse lieven$ git remote add jduda git://github.com/jduda/misterhouse.git
foamy:misterhouse lieven$ git remote show 
jduda
origin
foamy:misterhouse lieven$ git remote show jduda
* remote jduda
  Fetch URL: git://github.com/jduda/misterhouse.git
  Push  URL: git://github.com/jduda/misterhouse.git
  HEAD branch: master
  Remote branches:
    add_android_callerid_master new (next fetch will store in remotes/jduda)
    android_callerid            new (next fetch will store in remotes/jduda)
    insteon                     new (next fetch will store in remotes/jduda)
    jduda_working               new (next fetch will store in remotes/jduda)
    master                      new (next fetch will store in remotes/jduda)
  Local refs configured for 'git push':
    insteon pushes to insteon (local out of date)
    master  pushes to master  (up to date)
foamy:misterhouse lieven$ git fetch jduda
From git://github.com/jduda/misterhouse
 * [new branch]      add_android_callerid_master -> jduda/add_android_callerid_master
 * [new branch]      android_callerid -> jduda/android_callerid
 * [new branch]      insteon    -> jduda/insteon
 * [new branch]      jduda_working -> jduda/jduda_working
 * [new branch]      master     -> jduda/master
foamy:misterhouse lieven$ git cherry-pick c3df16f5ade77f9f080c7cc0f76b27fb36c62e8e
[master 6662dd0] Remove default android_server_port.
 Author: Jim Duda <[email protected]>
 1 file changed, 1 insertion(+), 1 deletion(-)
foamy:misterhouse lieven$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)
foamy:misterhouse lieven$ git push origin
Counting objects: 7, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 496 bytes, done.
Total 4 (delta 3), reused 0 (delta 0)
To [email protected]:hollie/misterhouse.git
   06f01c3..6662dd0  master -> master

Done!

Add a custom footer
Add a custom sidebar
Clone this wiki locally