add CONTRIBUTING.md, fix whats_new STYLE

.github/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Workflow
+
+- assuming you are working with `git` from a command line
+- assuming your GitHub username is `username`
+- `github.com/sappelhoff/pyprep` is `upstream`
+- `github.com/username/pyprep` is `origin` (your *fork*)
+
+## Syncing your fork's `master` with `upstream master`
+
+- first, you start with *forking* `upstream`
+- then, you continue by *cloning* your fork: `git clone https://github.com/username/pyprep`
+    - you'll have your own `master` branch there
+- **you always want to make sure that your fork's `master` and `upstream master` are aligned**
+    - to do this, you work with *git remotes*
+    - Note: this also means that you NEVER work on `master` (unless you know
+      what you are doing) ... because you want to always be able to SYNC your
+      fork with `upstream`, which would mean losing your own work on `master`
+- use `git remote -v` to list your configured remotes
+    - initially this will only list `origin` ... a bit like this maybe:
+
+```Text
+origin	https://github.com/username/pyprep (fetch)
+origin	https://github.com/username/pyprep (push)
+```
+
+- Now you want to add `upstream` as a remote. Use
+  `git remote add upstream https://github.com/sappelhoff/pyprep`
+- again, do `git remote -v`, it should look like this:
+
+```Text
+origin	https://github.com/username/pyprep (fetch)
+origin	https://github.com/username/pyprep (push)
+upstream	https://github.com/sappelhoff/pyprep (fetch)
+upstream	https://github.com/sappelhoff/pyprep (push)
+
+```
+
+- Now you can use your `upstream` *remote* to make sure your fork's `master` is
+  up to date.
+    1.  `git checkout master` to make sure you are on your `master` branch
+    1. Make sure you do not have any changes on your `master`, because we will
+       discard them!
+    1. `git pull upstream master` SYNC your fork and `upstream`
+    1. sometimes there are issues, so to be safe, do:
+       `git reset --hard upstream/master` ... this makes sure that both
+       branches are really synced.
+    1. ensure with another `git pull upstream master` ... this should say
+       "already up to date"
+
+## Working on a feature (and rebasing)
+
+### Working on a feature
+
+- before working on any feature: always do `git checkout master` and
+  `git pull upstream master`
+- then make your new branch to work on and check it out, for example
+  `git checkout -b my_feature`
+    - do your work
+    - submit a pull request
+    - hope you are lucky and nobody did work in between
+- however IF somebody did work in between, we need to *rebase*. Just follow the
+  steps below
+
+### Rebasing without conflicts
+
+1. sync `master` through: `git checkout master` and `git pull upstream master`
+1. go back to your branch and rebase it: `git checkout my_feature` and then
+   `git rebase master`
+
+Now it could be that you are lucky and there no conflicts ... in that case, the
+rebase just works and you can then finish up by *force pushing* your rebased
+branch: `git push -f my_feature` ... you need to force it, because rebasing
+changed the history of your branch. But don't worry, if rebasing "just worked"
+without any conflicts, this should be very safe.
+
+### Rebasing WITH conflicts
+
+In case you are unlucky, there are conflicts and you'll have to resolve them
+step by step ... `git` will be in *rebase* mode and try to rebase one commit
+after another ... for each commit where conflicts are detected, it'll stop.
+
+Then you have to do: `git status` to see conflicting files ... then edit these
+files to resolve conflicts ... then `git add <filename>` ... and then
+`git rebase --continue` to go on to the next commit, rinse and repeat.
+
+**NOTE: the conflict resolution part is the dangerous part that can get very
+messy and where you can actually lose stuff ... so make backups of your branch
+before.**
+
+After everything is resolved, you can again do `git push -f my_feature`.
+
+If you screw up **during** rebasing and you panic, you can do
+`git rebase --abort` and start again.
+
+### Rebasing ... panic mode (or "the easy way")
+
+If nothing helps and you just don't know how to resolve the issues and
+conflicts that arise during rebasing, just make a new branch:
+    1. `git checkout master`
+    1. `git pull upstream master`
+    1. `git checkout -b my_feature_2nd_attempt`
+
+... and apply your changes manually.
+
+This method is not really a `git` workflow, ... but in cases where there are
+only few changes, this is often a practical solution.

README.rst

@@ -62,6 +62,8 @@ Contributions are welcome! You should have read the references below. After
 that, feel free to submit pull requests. Be sure to always include tests for
 all new code that you introduce (whenever possible).
 
+See also our `CONTRIBUTING.md <https://github.com/sappelhoff/pyprep/blob/master/.github/CONTRIBUTING.md>`_!
+
 References
 ==========
 

docs/whats_new.rst

@@ -21,27 +21,25 @@ Current
 Changelog
 ~~~~~~~~~
 
-- Included a boolean which indicates if detrend should be done internally or not for the use of find_noisy_channels in reference.py. `Yorguin Mantilla`_
-- Robust average referencing + tests by  `Victor Xiang`_
-- Removing trend in the EEG data by high pass filtering and local linear regression + tests `Aamna Lawrence`_
-- Finding noisy channels with comparable output to Matlab +tests-including test for ransac `Aamna Lawrence`_
-- Stringing all the things together for the PREP pipeline +tests `Victor Xiang`_
-- Finding noisy channels with comparable output to Matlab +tests-including test for ransac `Aamna Lawrence`_
-- Finding the appropriate parameters in the MNE notch filter for implementing clean line noise functionality of Eeglab `Aamna Lawrence`_
-- Finding the reason for the difference between the Matlab and Pyprep’s output- Probably minor differences in the filter functions and also rounding done by functions like quantile `Victor Xiang`_  and `Aamna Lawrence`_
-- Overall debugging `Victor Xiang`_  and `Aamna Lawrence`_
-
+- Include a boolean ``do_detrend`` in :meth:`reference.robust_reference` to indicate whether detrend should be done internally or not for the use with :mod:`find_noisy_channels`, by `Yorguin Mantilla`_ (`#9 <https://github.com/sappelhoff/pyprep/pull/9>`_)
+- Robust average referencing + tests, by  `Victor Xiang`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Removing trend in the EEG data by high pass filtering and local linear regression + tests, by `Aamna Lawrence`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Finding noisy channels with comparable output to Matlab +tests-including test for ransac, by `Aamna Lawrence`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Stringing all the things together for the PREP pipeline +tests, by `Victor Xiang`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Finding noisy channels with comparable output to Matlab +tests-including test for ransac, by `Aamna Lawrence`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Finding the appropriate parameters in the MNE notch filter for implementing clean line noise functionality of Eeglab, by `Aamna Lawrence`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Finding the reason for the difference between the Matlab and Pyprep’s output- Probably minor differences in the filter functions and also rounding done by functions like quantile, by `Victor Xiang`_  and `Aamna Lawrence`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
 
 Bug
 ~~~
 
-- In find_noisy_channels the signal detrend is accidentally undone which destabilized the RANSAC. The detrend is now done over the NoisyChannels.raw_mne object to avoid this bug and to force that any signal in there is detrended like in matlab's prep. By `Yorguin Mantilla`_ (`#29 <https://github.com/sappelhoff/pyprep/pull/9>`_)
+- Prevent an undoing of the detrending in :mod:`find_noisy_channels`, by `Yorguin Mantilla`_ (`#9 <https://github.com/sappelhoff/pyprep/pull/9>`_)
 
 API
 ~~~
 
-- Oversaw modularization of PREP pipeline's submodules and a scikit learn style :func:`pyprep.fit` by `Adam Li`_
-- Oversaw ChangeLog by `Victor Xiang`_  and `Aamna Lawrence`_ for transitioning pyPrep to Version 0.3.0 by `Adam Li`_
+- Oversaw modularization of PREP pipeline's submodules and a scikit learn style :func:`pyprep.fit`, by `Adam Li`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
+- Oversaw ChangeLog by `Victor Xiang`_  and `Aamna Lawrence`_ for transitioning pyPrep to Version 0.3.0, by `Adam Li`_ (`#6 <https://github.com/sappelhoff/pyprep/pull/6>`_)
 
 .. _changes_0_2_3:
 
@@ -51,7 +49,7 @@ Version 0.2.3
 Doc
 ~~~
 
-- update formatting and docs and fix tags and releases post-hoc by `Stefan Appelhoff`_
+- update formatting and docs and fix tags and releases post-hoc, by `Stefan Appelhoff`_
 
 .. _changes_0_2_2:
 
@@ -61,7 +59,7 @@ Version 0.2.2
 Bug
 ~~~
 
-- mne epochs index start at 0, not 1 by `Stefan Appelhoff`_ (`3780abb <https://github.com/sappelhoff/pyprep/commit/3780abb922ebb790c74d3e871e2958d87d8c7e23>`_)
+- mne epochs index start at 0, not 1, by `Stefan Appelhoff`_ (`3780abb <https://github.com/sappelhoff/pyprep/commit/3780abb922ebb790c74d3e871e2958d87d8c7e23>`_)
 
 .. _changes_0_2_1:
 
@@ -71,7 +69,7 @@ Version 0.2.1
 Changelog
 ~~~~~~~~~
 
-- Add :func:`find_bad_epochs` based on the FASTER algorithm by `Stefan Appelhoff`_ (`0fa9c06 <https://github.com/sappelhoff/pyprep/commit/0fa9c065481c4cbaaf83b275f92b16b8807810b5>`_)
+- Add :func:`find_bad_epochs` based on the FASTER algorithm, by `Stefan Appelhoff`_ (`0fa9c06 <https://github.com/sappelhoff/pyprep/commit/0fa9c065481c4cbaaf83b275f92b16b8807810b5>`_)
 
 
 Authors
@@ -81,8 +79,8 @@ People who contributed to this software (in alphabetical order)
 * Stefan Appelhoff
 * Aamna Lawrence
 * Adam Li
-* Victor Xiang
 * Yorguin Mantilla
+* Victor Xiang
 
 .. _Stefan Appelhoff: http://stefanappelhoff.com/
 .. _Aamna Lawrence: https://github.com/AamnaLawrence