Contributing
================

Issues
--------
The GitHub Issues is used to track the development progress, issues,
bugs, feature requests.

However, the installation and usage related problems *should not* go to
the Issues, while the Wiki (TODO) or mailing lists (TODO) should be adopted
for those purposes.


Pull Requests
----------------
So you already have a patch, an improvement, or even a new feature?
It's GREAT!  And let's have it!

To make a nice pull request (PR), the following things should be noted:

* Please adhere to the [Code Guidelines](#code-guidelines) used
  throughout the project, and other requirements (e.g., test).
* The PR should generally go to the ``master`` branch;
  the ``gh-pages`` branch should be generated from the documentation
  source files.
* It is recommended to use *topic/feature branch* for a PR.
* A PR should focus on one clear thing, so making multiple smaller PRs
  is better than making one large PR.
* A PR should be made of many commits where appropriate, with each commit
  be a small, atomic change representing one step in the development.

The following procedure is the recommended way to get your work
incorporated in the project:

1. [Fork](https://help.github.com/fork-a-repo/) the project, clone your
   fork, and configure the remotes:

   ```sh
   # Clone your fork of the repo into the current directory
   git clone https://github.com/<your-username>/fg21sim.git
   # Navigate to the newly cloned directory
   cd fg21sim
   # Assign the original repo to a remote called "upstream"
   git remote add upstream https://github.com/liweitianux/fg21sim.git
   ```

2. If you cloned a while ago, get the latest changes from upstream:

   ```sh
   git checkout master
   git pull upstream master
   ```

3. Create a new topic branch (off the main project development branch)
   to contain your feature, change, or fix:

   ```sh
   git checkout -b <topic-branch-name>
   ```

4. Commit your changes in logical chunks. Please adhere to these
   [git commit message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
   Use Git's [interactive rebase](https://help.github.com/articles/interactive-rebase)
   feature to tidy up your commits before making them public.

5. Locally merge (or rebase) the upstream development branch into your
   topic branch:

   ```sh
   git pull [--rebase] upstream master
   ```

6. Push your topic branch up to your fork:

   ```sh
   git push origin <topic-branch-name>
   ```

7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
    with a clear title and description against the `master` branch.


Code Guidelines
-------------------

### Python

Adhere to the [PEP 8](https://www.python.org/dev/peps/pep-0008) code style
(also a [much prettier version of PEP 8](http://pep8.org)).
And the [code style](http://docs.python-guide.org/en/latest/writing/style/) from
[The Hitchhiker's Guide to Python](http://docs.python-guide.org/) is worth
reading.

It is strongly recommended to check the code with [``flake8``](https://gitlab.com/pycqa/flake8),
which wraps ``pep8``, ``pyflakes``, and other checkers together.
So make sure it is installed before carrying on.

* Vim users:

  1. Recommend to install the [``spf13-vim``](https://github.com/spf13/spf13-vim)
     configuration distribution, which already integrates the nice
     [``syntastic``](https://github.com/scrooloose/syntastic) syntax checking
     plugin;

  2. Add the following recommended settings to ``~/.vimrc.local``:

     ```vim
     let g:syntastic_always_populate_loc_list = 1
     let g:syntastic_auto_loc_list = 1
     let g:syntastic_check_on_open = 1
     let g:syntastic_check_on_wq = 0
     ```
   3. Check syntax manually with command ``:SyntasticCheck``, then browse
      the found errors/warnings in a subwindow with command ``:Errors``,
      and jump using commands ``:lnext`` and ``:lprev``.

* Emacs users:

  1. The [``spacemacs``](https://github.com/syl20bnr/spacemacs) is a great
     configuration distribution to use.

  2. Enable the [``syntax-checking``](https://github.com/syl20bnr/spacemacs/blob/master/layers/syntax-checking/README.org) layer,
     and you're ready to go.


Documentation Guidelines
------------------------------

### Python

Please adhere to the [NumPy/SciPy Documentation Guide](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt),
thus the [``Sphinx``](http://www.sphinx-doc.org/) tool can be used to create the documentation at ease.

There is also an [Example NumPy Style Python Docstrings](http://www.sphinx-doc.org/en/stable/ext/example_numpy.html) for a quick reference.


License
-------
By contributing your code, you agree to license your contribution under
the [MIT License](LICENSE).

By contributing to the documentation, you agree to license your contribution
under the [Creative Commons Attribution 3.0 license](https://creativecommons.org/licenses/by/3.0/us/deed.en_US).