Contributing¶
Maintaining this package is tricky because of its inter-language operability. In particular this requires keeping up with API changes to Python packages (e.g. pandas), R packages (e.g. lmerTest) as well as changes in rpy2 (which tend to break between versions), the interface package between them. For these reasons contributions are always welcome! Checkout the development roadmap on Github. Also note the diagram and explanation below which illustrate how code development cycles work and how automated deployment is handled through Travis CI.
Development Cycle and workflow¶
All automation for testing, documentation, and packaging is handled through Github Actions. We use separate workflows to handle testing and packaging.
Testing¶
Any pushes or PRs against the master
branch will trigger the Tests GA workflow. This is a simple workflow that:
sets up a
conda
environment with requiredR
dependenciesinstalls the latest code from the
master
branchruns tests and builds documentation (as an additional testing layer)
Packaging Stable Releases¶
A stable release can be installed from pip
or from conda
using the -c ejolly
channel flag. Packaging a stable release requires building 3 artifacts:
Conda packages for multiple platforms uploaded to the main
ejolly
channel on anaconda cloudA pip installable package uploaded to Pypi
Documentation site deployed to github pages
To create a new release:
Publish a new release via github
Manually trigger the Build and Build_noarch workflows and enable uploading to the main channel on anaconda, uploading to pypi, and deploying documentation
Note: Previously this process was automated to trigger when a github release is made, but this seems to be unreliable as the commit hash is missing and causes runners to not find the built tarballs
Packaging Development Releases¶
Development releases can be install directly from the master
branch on github using pip install git+https://github.com/ejolly/pymer4.git
or conda using the -c ejolly/label/pre-release
channel flag.
A development release only includes 1 artifact:
Conda packages for multiple platforms uploaded to the
ejolly/label/pre-release
channel on anaconda cloud
Development releases are created the same way as stable releases using the same Build and Build_noarch workflows, but choosing the “pre-release” option for uploading to anaconda cloud and disabling pypi and documentation deploys. The default options for these works flow will simply build packages but perform no uploading at all which can useful for testing package builds.
Updating deployed documentation¶
To deploy only documentation changes you can use either the Build workflow and enable the documentation deploy or the Docs workflow which is a bit faster as it skips packaging building.
Code Guidelines¶
Please use the black code formatter for styling code. Any easy way to check if code is formatted properly is to use a git pre-commit hook. After installing black, just create a file called .git/hooks/pre-commit
and put the following inside:
#!/bin/sh black --check .
This will prevent the use of the git commit
command if black notes any files that have not been formatted. Just format those files and you should be able to proceed with the commit!
Please use google style docstrings for documenting all functions, methods, and classes.
Please be sure to include tests with any code submissions and verify they pass using pytest. To run all package tests you can use pytest -s --capture=no
in the project root. To run specific tests you can point to a file or even a test function within a file, e.g. pytest pymer4/test/test_models.py -k "test_gaussian_lm"
Versioning Guidelines¶
The current pymer4
scheme is PEP 440 compliant with two and only two forms of version strings: M.N.P
and M.N.P.devX
. Versions with the .devX
designation denote development versions typically on the master
branch or conda
pre-release channel.
This simplifed scheme is not illustrated in the PEP 440 examples, but if was it would be described as “major.minor.micro” with development releases. To illustrate, the version sequence would look like this:
0.7.0 0.7.1.dev0 0.7.1.dev1 0.7.1
The third digit(s) in the pymer4
scheme, i.e. PEP 440 “micro,” are not strictly necessary but are useful for semantically versioned “patch” designations. The .devX
extension on the other hand denotes a sequence of incremental work in progress like the alpha, beta, developmental, release candidate system without the alphabet soup.
Documentation Guidelines¶
Documentation is written with sphinx using the bootstrap theme. Tutorial usage of package features is written using sphinx gallery.
To edit and build docs locally you’ll need to install these packages using: pip install sphinx sphinx_bootstrap_theme sphinx-gallery
. Then from within the docs
folder you can run make html
.
To add new examples to the tutorials simply create a new .py
file in the examples/
directory that begins with example_
. Any python code will be executed with outputs when the make html
command is run and automatically rendered in the tutorial gallery. You can add non-code comments with rST syntax using other files in the examples/
directory as a guide.
In addition to making it easy to create standalone examples of package features, the tutorial gallery serves as another layer of testing for the package. This can be really useful to ensure previous functionality is preserved when adding new features or fixing issues.