1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
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).
|
