Browse Source

contributing instructions added

dev-gf-shakemap
braunfuss 3 years ago
parent
commit
d614521d04
  1. 124
      CONTRIBUTING.md

124
CONTRIBUTING.md

@ -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/>.
Loading…
Cancel
Save