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//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 ``` 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 ``` 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. 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).