Skip to content

Latest commit

 

History

History
143 lines (104 loc) · 4.85 KB

CONTRIBUTING.md

File metadata and controls

143 lines (104 loc) · 4.85 KB

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 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 the project, clone your fork, and configure the remotes:

    # 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:

    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:

    git checkout -b <topic-branch-name>

  4. Commit your changes in logical chunks. Please adhere to these git commit message guidelines. Use Git's 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:

    git pull [--rebase] upstream master

  6. Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  7. Open a Pull Request with a clear title and description against the master branch.

Code Guidelines

Python

Adhere to the PEP 8 code style (also a much prettier version of PEP 8). And the code style from The Hitchhiker's Guide to Python is worth reading.

It is strongly recommended to check the code with 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 configuration distribution, which already integrates the nice syntastic syntax checking plugin;

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

      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 is a great configuration distribution to use.

    2. Enable the syntax-checking layer, and you're ready to go.

Documentation Guidelines

Python

Please adhere to the NumPy/SciPy Documentation Guide, thus the Sphinx tool can be used to create the documentation at ease.

There is also an Example NumPy Style Python Docstrings for a quick reference.

License

By contributing your code, you agree to license your contribution under the MIT License.

By contributing to the documentation, you agree to license your contribution under the Creative Commons Attribution 3.0 license.