Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Code of Conduct¶
Everyone interacting in the PyPgk RTD01 project’s code base, issue tracker, and any communication channels is expected to follow the PyPA Code of Conduct.
Report bugs at https://github.com/goerz-testing/pypgk_rtd01/issues.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug, ideally a minimal but complete script or notebook.
All error messages in full, as plain text. If the output is long, attach it as a file.
The best way to send feedback is to file an issue at https://github.com/goerz-testing/pypgk_rtd01/issues.
If you are proposing a feature:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
The pull request should include tests.
If the pull request adds functionality, the docs should be updated.
Check https://travis-ci.org/goerz-testing/pypgk_rtd01/pull_requests and make sure that the tests pass for all supported Python versions.
Ready to contribute? Follow Aaron Meurer’s Git Workflow Notes (with
goerz-testing/pypgk_rtd01 instead of
Clone the repository from
Fork the repo on GitHub to your personal account.
Add your fork as a remote.
Pull in the latest changes from the master branch.
Create a topic branch.
Make your changes and commit them (testing locally).
Push changes to the topic branch on your remote.
Make a pull request against the base master branch through the Github website of your fork.
The project uses tox for automated testing accross multiple versions of Python and for various development tasks such as linting and generating the documentation. See Development Prerequisites for details.
There is also a
Makefile that wraps around tox, for
convenience on Unix-based systems. In your checked-out clone, run
$ make help
to see the available make targets. If you cannot use
make, but want to use
tox directly (e.g., on Windows), run
$ tox -av
to see a list of tox environments and a description.
Contributing to the package’s developments requires that you have Python 3.7 and tox installed. It is strongly recommended that you also have installations of all other supported Python versions. The recommended way to install multiple versions of Python at the same time is through pyenv (or pyenv-win on Windows).
For developers with direct access to the repository,
PyPgk RTD01 uses a simple branching model where all
developments happens directly on the
master branch. Releases are tags on
master. All commits on
master should pass all tests and be
well-documented. This is so that
git bisect can be effective. For any
non-trivial issue, it is recommended to create a topic branch, instead of
master. There are no restrictions on commits on topic branches,
they do not need to contain complete documentation, pass any tests, or even be
able to run.
To create a topic-branch named
$ git branch issue1 $ git checkout issue1
You can then make commits, and push them to Github to trigger Continuous Integration testing:
$ git push -u origin issue1
Commit early and often! At the same time, try to keep your topic branch as clean and organized as possible. If you have not yet pushed your topic branch to the “origin” remote:
Avoid having a series of meaningless granular commits like “start bugfix”, “continue development”, “add more work on bugfix”, “fix typos”, and so forth. Instead, use
git commit --amendto add to your previous commit. This is the ideal way to “commit early and often”. You do not have to wait until a commit is “perfect”; it is a good idea to make hourly/daily “snapshots” of work in progress. Amending a commit also allows you to change the commit message of your last commit.
You can combine multiple existing commits by “squashing” them. For example, use
git rebase -i HEAD~4to combined the previous four commits into one. See the “Rewriting History” section of Pro Git book for details (if you feel this is too far outside of your git comfort zone, just skip it).
If you work on a topic branch for a long time, and there is significant work on
masterin the meantime, periodically rebase your topic branch on the current master (
git rebase master). Avoid merging
masterinto your topic branch. See Merging vs. Rebasing.
If you have already pushed your topic branch to the remote origin, you have to
be a bit more careful. If you are sure that you are the only one working on
that topic branch, you can still follow the above guidelines, and force-push
the issue branch (
git push --force). This also applies if you are an
external contributor preparing a pull request in your own clone of the project.
If you are collaborating with others on the topic branch, coordinate with them
whether they are OK with rewriting the history. If not, merge instead of
rebasing. You must never rewrite history on the
master branch (nor will you
be able to, as the
master branch is “protected” and can only be force-pushed to
in coordination with the project maintainer). If something goes wrong with any
advanced “history rewriting”, there is always “git reflog” as a safety net
– you will never lose work that was committed before.
When you are done with a topic branch (the issue has been fixed), finish up by
merging the topic branch back into
$ git checkout master $ git merge --no-ff issue1
--no-ff option is critical, so that an explicit merge commit is created
(especially if you rebased). Summarize the changes of the branch relative to
master in the commit message.
Then, you can push master and delete the topic branch both locally and on Github:
$ git push origin master $ git push --delete origin issue1 $ git branch -D issue1
Commit Message Guidelines¶
Write commit messages according to this template:
Short (50 chars or less) summary ("subject line") More detailed explanatory text. Wrap it to 72 characters. The blank line separating the summary from the body is critical (unless you omit the body entirely). Write your subject line in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. A properly formed git commit subject line should always be able to complete the sentence "If applied, this commit will <your subject line here>". Further paragraphs come after blank lines. - Bullet points are okay, too. - Typically a hyphen or asterisk is used for the bullet, followed by a single space. Use a hanging indent. You should reference any issue that is being addressed in the commit, as e.g. "#1" for issue #1. If the commit closes an issue, state this on the last line of the message (see below). This will automatically close the issue on Github as soon as the commit is pushed there. Closes #1
See Closing issues using keywords for details on references to issues that Github will understand.
From a checkout of the
pypgk_rtd01 repository you can use
$ make test
to run the entire test suite, or
$ tox -e py37-test,py38-test
make is not available.
The tests are organized in the
tests subfolder. It includes python scripts
whose name start with
test_, which contain functions whose names also start
test_. Any such functions in any such files are picked up by pytest
for testing. In addition, doctests from any docstring or any documentation
*.rst) are picked up (by the pytest doctest plugin).
Lastly, all Jupyter notebooks in the documentation are validated as a test,
through the nbval plugin.
All code must be compatible with PEP 8. The line length limit is 79 characters, although exceptions are permissible if this improves readability significantly.
Beyond PEP 8, this project adopts the Black code style, with
--skip-string-normalization --line-length 79. You can
make black-check or
tox -e run-blackcheck to check adherence to the
code style, and
make black or
tox -e run-black to apply it.
Imports within python modules must be sorted according to the isort
setup.cfg. The command
make isort-check or
run-isortcheck checks whether all imports are sorted correctly, and
tox -e run-isort modifies all Python modules in-place with the
The code style is enforced as part of the test suite, as well as through git pre-commit hooks that prevent committing code not does not meet the requirements. These hooks are managed through the pre-commit framework.
You may use
make flake8-check or
tox -e run-flake8 and
tox -e run-pylint for additional checks on the code with
flake8 and pylint, but there is no strict requirement for a perfect score
with either one of these linters. They only serve as a guideline for code that
might be improved.
PyPgk RTD01 could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
The package documentation is generated with Sphinx, the
documentation (and docstrings) are formatted using the
Restructured Text markup language (file extension
See also the Matplotlib Sphinx cheat sheet for some helpful tips.
Each function or class must have a docstring; this docstring must be written in the “Google Style” format (as implemented by Sphinx’ napoleon extension). Docstrings and any other part of the documentation can include mathematical formulas in LaTeX syntax (using mathjax).
For module variables and class attributes, use a docstring “inline” immediately
after the definition. However, for instance attributes, it is preferable to include
an “Attributes:” section in the class docstring (instead of using “attribute
__init__). While attribute docstrings have the benefit that
it is less likely for there to be a mismatch between the documentation and the
implementation, they also have some significant drawbacks, for example: They do
not show up in
<class>? in IPython, they tend to make
__init__ much harder to read, and they don’t work for classes defined via
__init__ method should never have a docstring; it’s arguments are
described in the class docstring instead.
At any point, from a checkout of the
repository, you may run
$ make docs
$ tox -e docs
to generate the documentation locally.
In short, versions number follow the pattern major.minor.patch, e.g.
0.1.0 for the first release, and
1.0.0 for the first stable release.
If necessary, pre-release versions might be published as e.g:
1.0.0-dev1 # developer's preview 1 for release 1.0.0 1.0.0-rc1 # release candidate 1 for 1.0.0
Errors in the release metadata or documentation only may be fixed in a post-release, e.g.:
1.0.0.post1 # first post-release after 1.0.0
Post-releases should be used sparingly, but they are acceptable even though they are not supported by the Semantic Versioning specification.
The current version is available through the
__version__ attribute of the
>>> import pypgk_rtd01 >>> pypgk_rtd01.__version__
__version__ on the master branch should either be the
version number of the last release, with “+dev” appended (as a
“local version identifier”), or the version number of the next planned
release, with “-dev” appended (“pre-release identifier” with extra dash).
The version string “1.0.0-dev1+dev” is a valid value after the “1.0.0-dev1”
pre-release. The “+dev” suffix must never be included in a release to PyPI.
Note that twine applies normalization to the above recommended forms to make them strictly compatible with PEP 440, before uploading to PyPI. Users installing the package through pip may use the original version specification as well as the normalized one (or any other variation that normalizes to the same result).
When making a release via
$ make release
the above versioning conventions will be taken into account automatically.
Releases must be tagged in git, using the version string prefixed by “v”,
v1.0.0. This makes them available at