How to contribute

Important

The markup used for the documentation is reStructuredText.

We maintain the EEW Simulation Package for Python as an open-source project for common interest. To allow your contributions if provided via a pull-request, you should follow the following rules:

  1. Make sure the package can be installed from source (requires to remove the pre-installed version as bellow or to increment version number):

    python -m pip uninstall pyshake
python -m pip install ./

  2. Make sure all dependencies are listed in requirements.txt.

  3. Make sure version number is upgraded in setup.py in order to trigger pip update and consistent with docs/conf.py (variable release).

  4. Make sure all features are documented and test documentation with (requires sphinx installed) and check the result (open _build/html/index.html):

    sphinx-apidoc -f -o docs pyshake
cd docs
make clean html

  5. Submit your contribution via a pull request from a branch of a fork, see the example below.

  6. Please make sure your commits and pull requests are properly described following common best practices such as https://www.atlassian.com/blog/git/written-unwritten-guide-pull-requests.

  7. Know that the title of your pull request will be used as the default merge message for all squashed commits (https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests).

Please also be patient with the maintenance team, and remember that your help is very welcomed!

How to PR from fork branch

  1. Create a fork of the main project online at https://github.com/ATTAC-EEW-in-Central-America/pyShake

  2. Clone the main project, and go in the clone:

    git clone https://github.com/ATTAC-EEW-in-Central-America/pyShake
cd pyShake

  3. Setup pushing to your fork (e.g., with mine, have your own instead):

    git remote set-url --add --push origin https://github.com/<YOUR USER NAME>/pyShake

  4. Push your contribution to a branch of your fork:

    git checkout -b <CONTRIB NAME>
git add <files with contrib>
git commit
git push origin  <CONTRIB NAME>

Note

Note that git provides a direct link to create your pull request, e.g.:

...
remote: Create a pull request for '<CONTRIB NAME>' on GitHub by visiting:
remote:      https://github.com/ATTAC-EEW-in-Central-America/pyshake

Bonus

Project owners might push minor contribution from their master branch to both their forks and the main project repo:

git push all master