A seismology toolkit for Python
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

124 lines
4.0 KiB

  1. # Pyrocko development environment and contribution guide
  2. ## Language
  3. Pyrocko is written in the Python programming language (versions ==2.7 and >=3.4).
  4. ## Deployment
  5. Pyrocko uses Setuptools for its installation script. See `setup.py` and
  6. `setup.cfg` in the project root directory.
  7. ## Versioning and releases
  8. Git is used for version control. Use development branches for new features.
  9. Master branch should always point to a stable version.
  10. The Pyrocko project adheres to a [calendar dating versioning scheme](https://calver.org/#scheme), using the vYYYY.MM.DD format.
  11. Notable changes must be documented in the file `CHANGELOG.md`. The format of
  12. the change log is based on [Keep a
  13. Changelog](https://keepachangelog.com/en/1.0.0/).
  14. ### Commit message conventions
  15. * start with lower case
  16. * colon-prepend affected component
  17. * try to use imperative form
  18. * examples:
  19. - `docs: add section about weighting`
  20. - `waveform targets: correct typo in component names`
  21. - `waveform targets: fix issues with misaligned traces`
  22. ### Branching policy
  23. * The `master` branch should point to a stable, tagged version of Pyrocko.
  24. * The `dev` branch is used to aggregate new features before releasing.
  25. * Use topic branches to develop new features.
  26. ### Rebase small changes before pushing
  27. Try to rebase little changes on top of master (or any other development branch)
  28. before pushing, it makes the history much better readable. Here is a safe way
  29. to do so.
  30. *If we have already commited and merged changes to local master:*
  31. ```sh
  32. git checkout master
  33. git fetch origin # important, otherwise we rebase to outdated
  34. git rebase origin/master
  35. git push origin master
  36. ```
  37. with `git config --global pull.rebase true` this can be shortcutted to
  38. ```sh
  39. git pull
  40. ```
  41. *Or after we have commited to a feature branch:*
  42. ```sh
  43. git checkout feature
  44. git fetch origin
  45. git rebase origin/master
  46. git checkout master
  47. git merge origin/master
  48. git merge feature # should now be fast forward...
  49. git push origin master
  50. ```
  51. If during push it refuses to upload ('not fast forward...') then repeat the
  52. procedure, because someone else has pushed between your fetch and push.
  53. **Tip:** use `rebase -i ...` to simplify/fixup/beautify your changeset.
  54. ## Code style
  55. Pyrocko source code must follow the PEP8 coding standards. It must pass the
  56. code style check provided by the `flake8` tool.
  57. Additionally,
  58. * use i/n convention for indices and counts
  59. - e.g. `for istation in range(nstations):`
  60. * do not abbreviate words unless this would result in ridiculously long names
  61. * use British english, e.g.
  62. - 'modelling' rather than 'modeling'
  63. - 'analyser' rather than 'analyzer'
  64. - 'optimiser' rather than 'optimizer'
  65. * log and exception messages:
  66. - capital beginning
  67. - final period
  68. - Progress actions should end with `...`, e.g. `Generating report's archive...`
  69. - e.g. `raise ProblemDataNotAvailable('No problem data available (%s).' % dirname)`
  70. - in-text names must be quoted; not needed after colons
  71. * docstrings: TODO
  72. ## Documentation
  73. Pyrocko's documentation is built using the `Sphinx` tool. See the `docs`
  74. in the project root directory. Build with `make html` in `docs`.
  75. *Text style rules:*
  76. * titles: only capitalize first word
  77. * use British english
  78. ## License
  79. GNU General Public License, Version 3, 29 June 2007
  80. Copyright © 2018 Helmholtz Centre Potsdam GFZ German Research Centre for
  81. Geosciences, Potsdam, Germany and University of Kiel, Kiel, Germany.
  82. Pyrocko is free software: you can redistribute it and/or modify it under the
  83. terms of the GNU General Public License as published by the Free Software
  84. Foundation, either version 3 of the License, or (at your option) any later
  85. version. Pyrocko is distributed in the hope that it will be useful, but WITHOUT
  86. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  87. FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  88. You should have received a copy of the GNU General Public License along with
  89. this program. If not, see <http://www.gnu.org/licenses/>.