Merge branch 'master' into development

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contribution guidelines #
+
+## Reporting issues ##
+Make sure that what you are experiencing is actually an error and that it lies with homeshick (often it can be a git configuration error)
+
+### Questions ###
+If you have a question be sure to read [the documentation](https://github.com/andsens/homeshick/wiki) first.
+Often you will find the answer to it there.
+
+### Description ###
+As with bug reports everywhere else:
+* state the action(s) you took
+* explain what outcome you expected
+* describe the actual result
+
+You will also need to report which operating system you encountered the issue on
+and which shell you used (type `echo $SHELL` in your terminal if you are unsure).
+
+
+### Reproducing ###
+Unless you ran in to a [heisenbug](http://en.wikipedia.org/wiki/Heisenbug), 
+it should be possible to reproduce the bug in a testing environment.  
+To that end run `$HOME/.homesick/repos/homeshick/test/interactive` and reproduce the bug.  
+This script drops you into a new shell where `$HOME` is set to an (almost) empty temporary folder.
+If you cannot reproduce the bug there, the error is likely with your setup and not homeshick.
+Otherwise attach the commands you executed in that environment to the issue.
+
+## Pull requests ##
+
+### Code style ###
+* Indent with tabs and align with spaces.
+* Always use double brackets for `if` blocks
+
+### Content ###
+**Every PR should only contain one feature change, bug fix or typo correction.**
+
+Commits should be atomic units of work, if they are not you should rebase them so that they are
+(typo corrections from a previous change for example do not justify a commit).
+
+### Description ###
+The PR should clearly describe what problem the change fixes.
+A feature addition with no justification and use-case will be rejected.
+
+### Testing ###
+Unless the code-change is a refactor, you should always add unit tests.  
+When fixing a bug there should be a new test case that fails with the old code and succeeds with the new code.  
+When introducing a new feature, it should be tested extensively, a single test case will not suffice.
+
+Note that bats does not fail a test case when using double brackets.
+To assert variable values and file existance you *must* use single brackets!
+
+Also consider negative test cases (e.g. what happens when a non-existing castlename is passed as an argument?).
+
+You can read about the details of the testing framework
+[in the documentation](https://github.com/andsens/homeshick/wiki/Testing).

README.md

@@ -21,22 +21,23 @@ Quick install
 -------------
 
 homeshick is installed to your own home directory and does not require root privileges to be installed.
-
 ```sh
 git clone git://github.com/andsens/homeshick.git $HOME/.homesick/repos/homeshick
 ```
+*Note: If you'd like to help testing new features before they are released use `git clone --branch testing git://...`*
 
-To invoke homeshick from sh and its derivates (bash, zsh etc.) source the `homeshick.sh` script from your rc-script:
+To invoke homeshick, source the `homeshick.sh` script from your rc-script:
 ```sh
+# from sh and its derivates (bash, zsh etc.) 
 printf '\nsource "$HOME/.homesick/repos/homeshick/homeshick.sh"' >> $HOME/.bashrc
-```
-csh and derivatives (i.e. tcsh):
-```sh
+# csh and derivatives (i.e. tcsh)
 printf '\nalias homeshick source "$HOME/.homesick/repos/homeshick/bin/homeshick.csh"' >> $HOME/.cshrc
+# fish shell
+echo \n'source "$HOME/.homesick/repos/homeshick/homeshick.fish"' >> "$HOME/.config/fish/config.fish"
 ```
 
-fish shell:
+Contributing
+------------
 
-```sh
-echo \n'source "$HOME/.homesick/repos/homeshick/homeshick.fish"' >> "$HOME/.config/fish/config.fish"
-```
+Before submitting pull requests or reporting bugs, please make sure to read
+the [contribution guidelines](CONTRIBUTING.md).