|
|
@ -0,0 +1,124 @@ |
|
|
|
# Pyrocko development environment and contribution guide |
|
|
|
|
|
|
|
## Language |
|
|
|
|
|
|
|
Pyrocko is written in the Python programming language (versions ==2.7 and >=3.4). |
|
|
|
|
|
|
|
## Deployment |
|
|
|
|
|
|
|
Pyrocko uses Setuptools for its installation script. See `setup.py` and |
|
|
|
`setup.cfg` in the project root directory. |
|
|
|
|
|
|
|
## Versioning and releases |
|
|
|
|
|
|
|
Git is used for version control. Use development branches for new features. |
|
|
|
Master branch should always point to a stable version. |
|
|
|
|
|
|
|
The Pyrocko project adheres to a [calendar dating versioning scheme](https://calver.org/#scheme), using the vYYYY.MM.DD format. |
|
|
|
|
|
|
|
Notable changes must be documented in the file `CHANGELOG.md`. The format of |
|
|
|
the change log is based on [Keep a |
|
|
|
Changelog](https://keepachangelog.com/en/1.0.0/). |
|
|
|
|
|
|
|
### Commit message conventions |
|
|
|
|
|
|
|
* start with lower case |
|
|
|
* colon-prepend affected component |
|
|
|
* try to use imperative form |
|
|
|
* examples: |
|
|
|
- `docs: add section about weighting` |
|
|
|
- `waveform targets: correct typo in component names` |
|
|
|
- `waveform targets: fix issues with misaligned traces` |
|
|
|
|
|
|
|
### Branching policy |
|
|
|
|
|
|
|
* The `master` branch should point to a stable, tagged version of Pyrocko. |
|
|
|
* The `dev` branch is used to aggregate new features before releasing. |
|
|
|
* Use topic branches to develop new features. |
|
|
|
|
|
|
|
### Rebase small changes before pushing |
|
|
|
|
|
|
|
Try to rebase little changes on top of master (or any other development branch) |
|
|
|
before pushing, it makes the history much better readable. Here is a safe way |
|
|
|
to do so. |
|
|
|
|
|
|
|
*If we have already commited and merged changes to local master:* |
|
|
|
|
|
|
|
```sh |
|
|
|
git checkout master |
|
|
|
git fetch origin # important, otherwise we rebase to outdated |
|
|
|
git rebase origin/master |
|
|
|
git push origin master |
|
|
|
``` |
|
|
|
|
|
|
|
with `git config --global pull.rebase true` this can be shortcutted to |
|
|
|
|
|
|
|
```sh |
|
|
|
git pull |
|
|
|
``` |
|
|
|
|
|
|
|
*Or after we have commited to a feature branch:* |
|
|
|
|
|
|
|
```sh |
|
|
|
git checkout feature |
|
|
|
git fetch origin |
|
|
|
git rebase origin/master |
|
|
|
git checkout master |
|
|
|
git merge origin/master |
|
|
|
git merge feature # should now be fast forward... |
|
|
|
git push origin master |
|
|
|
``` |
|
|
|
|
|
|
|
If during push it refuses to upload ('not fast forward...') then repeat the |
|
|
|
procedure, because someone else has pushed between your fetch and push. |
|
|
|
|
|
|
|
**Tip:** use `rebase -i ...` to simplify/fixup/beautify your changeset. |
|
|
|
|
|
|
|
## Code style |
|
|
|
|
|
|
|
Pyrocko source code must follow the PEP8 coding standards. It must pass the |
|
|
|
code style check provided by the `flake8` tool. |
|
|
|
|
|
|
|
Additionally, |
|
|
|
|
|
|
|
* use i/n convention for indices and counts |
|
|
|
- e.g. `for istation in range(nstations):` |
|
|
|
* do not abbreviate words unless this would result in ridiculously long names |
|
|
|
* use British english, e.g. |
|
|
|
- 'modelling' rather than 'modeling' |
|
|
|
- 'analyser' rather than 'analyzer' |
|
|
|
- 'optimiser' rather than 'optimizer' |
|
|
|
* log and exception messages: |
|
|
|
- capital beginning |
|
|
|
- final period |
|
|
|
- Progress actions should end with `...`, e.g. `Generating report's archive...` |
|
|
|
- e.g. `raise ProblemDataNotAvailable('No problem data available (%s).' % dirname)` |
|
|
|
- in-text names must be quoted; not needed after colons |
|
|
|
* docstrings: TODO |
|
|
|
|
|
|
|
## Documentation |
|
|
|
|
|
|
|
Pyrocko's documentation is built using the `Sphinx` tool. See the `docs` |
|
|
|
in the project root directory. Build with `make html` in `docs`. |
|
|
|
|
|
|
|
*Text style rules:* |
|
|
|
|
|
|
|
* titles: only capitalize first word |
|
|
|
* use British english |
|
|
|
|
|
|
|
## License |
|
|
|
|
|
|
|
GNU General Public License, Version 3, 29 June 2007 |
|
|
|
|
|
|
|
Copyright © 2018 Helmholtz Centre Potsdam GFZ German Research Centre for |
|
|
|
Geosciences, Potsdam, Germany and University of Kiel, Kiel, Germany. |
|
|
|
|
|
|
|
Pyrocko is free software: you can redistribute it and/or modify it under the |
|
|
|
terms of the GNU General Public License as published by the Free Software |
|
|
|
Foundation, either version 3 of the License, or (at your option) any later |
|
|
|
version. Pyrocko is distributed in the hope that it will be useful, but WITHOUT |
|
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
|
|
|
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. |
|
|
|
You should have received a copy of the GNU General Public License along with |
|
|
|
this program. If not, see <http://www.gnu.org/licenses/>. |
|
|
|
|