Fork 0

contributing instructions added

braunfuss 4 years ago
parent 1d640e099f
commit d614521d04

@ -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
### 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:*
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
git pull
*Or after we have commited to a feature branch:*
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.
* 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/>.