-
Notifications
You must be signed in to change notification settings - Fork 130
Contributing
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 who just want to download and use such a version
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, skip this step and see the developing using git section 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 stable branch of MisterHouse is now cloned in the folder 'misterhouse'. This is the branch you want for using MisterHouse.
- The default branch is stable. If you need a specific branch you can now perform
git checkout <branch_name>. E.g. if you want the latest feature under development, then you'll probably want to checkout the branch called 'master'.
Note: if you're not sure what URL to use to access the source code with the clone command above, read this article.
Note 2: it is important to understand that if you just clone the repository, we have configured the repo to ensure you end up with the latest stable release of MisterHouse. The latest stable release is exactly what its name implies: it is a stable version that was released at a certain point in time. This version does not include the latest and greatest code. So If you want to experiment with the cutting-edge code you need to checkout the master branch. This is done with the commands that are listed below. These commands will create a directory named "misterhouse" in your current working directory. This means if you "cd /usr/local", the following command will create /usr/local/misterhouse
git clone git://github.com/hollie/misterhouse.git
cd misterhouse
git checkout master
Of course, once you have cloned the repository you want to keep track of the latest updates other developers commit to the repository. This is done with this command:
cd {path to misterhouse}
git pull
Perltidy is a Perl script which indents and reformats Perl scripts to make them follow a defined format making them easier to read. In order to use perltidy, you must install the perltidy program. Installation instructions can be found on the perltidy website.
Developers are NOT required to submit "tidy'd" code, but it is always appreciated. Also keep in mind that the entire code base will be "tidy'd" before every release. This could potentially cause the attribution of your contribution to be buried by a formatting commit performed by an administrator.
MisterHouse includes a configuration template located in bin/.perltidyrc. This template defines the formatting style that has been agreed upon by the MisterHouse community. You can manually run perltidy on a specific file by executing the following command:
perltidy -pro=<path to mh>/bin/.perltidyrc SomePerlFile.pl
Additionally, if you develop in a Mac or Linux environment, you can install a commit hook in git that will cause perltidy to be run automatically on any file that you commit. To install this hook use the following command:
<path to mh>/bin/githook-perltidy install
Finally, a script has also been included which will run perltidy on all perl files in the repository. It is envisioned that this script would be used by an administrator as part of the release process. This command can be run as follows:
<path to mh>/bin/perltidyall
A quick-start guide into using git.
- Create a github account and 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 to your account (single button click on the 'Fork' button in the right upper corner here or directly fork after you are logged into github with the credentials you created in the previous step). Now your account on github contains a fork of the top level MisterHouse repository. You can now work on your own fork to start contributing.
- Now, you need to get the code on your computer to work on it. In git this process is called 'cloning the repository'. Clone your fork to your local machine with:
git clone git@github.com:<your_account_on_github>/misterhouse.git
You now have a copy of the code on your computer that shows you the latest stable release.
- For developing, you don't need the stable release, but the development branch. This branch is called 'master'. To get that version of the files on your computer, enter the 'misterhouse' folder that was created in the previous command. Checkout the branch on which the development takes place with this command:
git checkout -b master origin/master
- 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 specifically for the contribution you want to make is easy:
git checkout -b <insert_descriptive_branch_name_here>
- Develop, test until you're satisfied with the changes.
- Now we need to tell git we want to put the changes in the repo. This is called 'staging'. Stage the files you want to commit:
git stage <files_you_changed>
If you are not sure what files to add, to a git status and see what the tool reports.
- Commit the changes you staged to the local repository on your computer:
git commit -m "Descriptive message here"
- Publish the changes to the repository on github so that other people can see what you changed. This process is called 'pushing'. Push the branch with your changes to your github repository. The github repository is called 'origin' since you cloned from that repo earlier. The command to do that goes like this:
git push origin <branch_name_you_created_earlier>, however the git protocol you used to clone your repository in step 3 doesn't support writing back to github, you have to use https. To make this the default, you may need to edit the./.git/configand replace:
[remote "origin"]
url = git://github.com/<your_account_on_github>/misterhouse.git
With:
[remote "origin"]
url = https://github.com/<your_account_on_github>/misterhouse.git
Then you can push using the following command;
git push origin <branch_name_you_created_earlier>
It will ask for your git userid and password during this step.
- One final step: You need to tell the others that you want to contribute your changes back to the original MisterHouse repository. This is done by creating a 'pull request'. Create the pull request by navigating to your github web page, 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, there are more details, see here and here. Remember to create the pull request against the
hollie:misterhouse/masterbranch.
All MisterHouse developers are now notified of your change and can easily check out your changes. If all is well, a single button click by one of the repo maintainers will integrate your changes into the main MisterHouse repo.
Now I hear you thinking: "Wow, that's a lot of steps, and you told us it would be easier than using SVN..."
Well, in practice, the first steps you do once to get the repo forked and setup on your computer
# go to https://github.com/hollie/misterhouse/wiki and click on Fork to get your copy
# check it appears correctly in https://github.com/<yourgitusername>/misterhouse
git clone git://github.com/yourgitusername/misterhouse.git
# NOTE: if you use git clone https://github.com/yourgitusername/misterhouse.git you shouldn't need to edit the config file as described below (I've not tested this)
# edit misterhouse/.git/config as above to set the default push protocol to https
# check you are on the master branch
git checkout -b master origin/master
Your development environment is now ready to prepare and upload a change;
git checkout -b A_Name_you_can_remember_describing_this_change
# edit (and add) the files you need to change
# when you are ready to push your changes from your development environment back to git;
# check what you have changed
git status
# for each file you have changed
git stage path/filename
git add path/filenane
git commit -m "some nice text describing your change"
git push origin A_Name_you_can_remember_describing_this_change
Please see above how to create the pull request to get your change in the queue to be incorporated into the master branch
It is not immediately visible from the steps described here, but integrating your change to the master branch is easy and can even be done through the web interface by the people who volunteer to merge back changes proposed by the other developers. A list of people who are able and willing to do so is listed below.
If at some point you want to update your branch to the latest hollie master run:
git pull git://github.com/hollie/misterhouse.git master
Be aware that any uncommitted changes could result in conflicts.
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:
git checkout master
Already on 'master'
git pull
Already up-to-date.
git reset --hard 06f01c3b7fca24bf55449077bd8c6dee0de668ae
HEAD is now at 06f01c3 Add support for CALLERID popup and other basic NOTIFICATIONS.
git push -f origin master
Total 0 (delta 0), reused 0 (delta 0)
To git@github.com:hollie/misterhouse.git
+ ff69f1f...06f01c3 master -> master (forced update)
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:
git remote add jduda git://github.com/jduda/misterhouse.git
git remote show
jduda
origin
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)
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
git cherry-pick c3df16f5ade77f9f080c7cc0f76b27fb36c62e8e
[master 6662dd0] Remove default android_server_port.
Author: Jim Duda <jim@duda.tzo.com>
1 file changed, 1 insertion(+), 1 deletion(-)
git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)
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 git@github.com:hollie/misterhouse.git
06f01c3..6662dd0 master -> master
- A general quick overview of basic git usage can be found here
- See here to see how to create a new stable release.
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 willing 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/enthusiasts 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)
mstovenour (Michael Stovenour)
krkeegan (Kevin)
hplato (Howard)
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.