If you’re interested in contributing to SCMData, we’d love to have you on board! This section of the docs will (once we’ve written it) detail how to get setup to contribute and how best to communicate.
All contributions are welcome, some possible suggestions include:
tutorials (or support questions which, once solved, result in a new tutorial :D)
improving the documentation
Please report issues or discuss feature requests in the SCMData issue tracker. If your issue is a feature request or a bug, please use the templates available, otherwise, simply open a normal issue :)
As a contributor, please follow a couple of conventions:
Create issues in the SCMData issue tracker for changes and enhancements, this ensures that everyone in the community has a chance to comment
Be welcoming to newcomers and encourage diverse new contributors from all backgrounds: see the Python Community Code of Conduct
Only push to your own branches, this allows people to force push to their own branches as they need without fear or causing others headaches
Start all pull requests as draft pull requests and only mark them as ready for review once they’ve been rebased onto master, this makes it much simpler for reviewers
Try and make lots of small pull requests, this makes it easier for reviewers and faster for everyone as review time grows exponentially with the number of lines in a pull request
To get setup as a developer, we recommend the following steps (if any of these tools are unfamiliar, please see the resources we recommend in Development tools):
Install conda and make
make virtual-environment, if that fails you can try doing it manually
Change your current directory to SCMData’s root directory (i.e. the one which contains
Create a virtual environment to use with SCMData
python3 -m venv venv
Activate your virtual environment
pip intall --upgrade pip
Install the development dependencies (very important, make sure your virtual environment is active before doing this)
pip install -e .[dev]
Make sure the tests pass by running
make test-all, if that fails the commands are
Activate your virtual environment
Run the unit and integration tests
pytest --cov -r a --cov-report term-missing
Whilst developing, unexpected things can go wrong (that’s why it’s called ‘developing’, if we knew what we were doing, it would already be ‘developed’). Normally, the fastest way to solve an issue is to contact us via the issue tracker. The other option is to debug yourself. For this purpose, we provide a list of the tools we use during our development as starting points for your search to find what has gone wrong.
This list of development tools is what we rely on to develop SCMData reliably and reproducibly. It gives you a few starting points in case things do go inexplicably wrong and you want to work out why. We include links with each of these tools to starting points that we think are useful, in case you want to learn more.
we use a blend of pytest and the inbuilt Python testing capabilities for our tests so checkout what we’ve already done in
teststo get a feel for how it works
we use Travis CI for our CI but there are a number of good providers
Jupyter is automatically included in your virtual environment if you follow our Getting setup instructions
We also use some other tools which aren’t necessarily the most familiar. Here we provide a list of these along with useful resources.
we use regex101.com to help us write and check our regular expressions, make sure the language is set to Python to make your life easy!
To help us focus on what the code does, not how it looks, we use a couple of automatic formatting tools.
These automatically format the code for us and tell use where the errors are.
To use them, after setting yourself up (see Getting setup), simply run
make format can only be run if you have committed all your work i.e. your working directory is ‘clean’.
This restriction is made to ensure that you don’t format code without being able to undo it, just in case something goes wrong.
Buiding the docs
After setting yourself up (see Getting setup), building the docs is as simple as running
make docs (note, run
make -B docs to force the docs to rebuild and ignore make when it says ‘… index.html is up to date’).
This will build the docs for you.
You can preview them by opening
docs/build/html/index.html in a browser.
For documentation we use Sphinx. To get ourselves started with Sphinx, we started with this example then used Sphinx’s getting started guide.
To get Sphinx to generate pdfs (rarely worth the hassle), you require Latexmk.
On a Mac this can be installed with
sudo tlmgr install latexmk.
You will most likely also need to install some other packages (if you don’t have the full distribution).
You can check which package contains any missing files with
tlmgr search --global --file [filename].
You can then install the packages with
sudo tlmgr install [package].
For our docstrings we use numpy style docstrings. For more information on these, here is the full guide and the quick reference we also use.
Test installation with dependencies
add a header for the new version between
masterand the latest bullet point
this should leave the section underneath the master header empty
git add .
git commit -m "release(vX.Y.Z)"
git tag vX.Y.Z
Test version updated as intended with
If uploading to PyPI, do the following (otherwise skip these steps)
Go to test PyPI and check that the new release is as intended. If it isn’t, stop and debug.
Test the install with
make test-testpypi-install(this doesn’t test all the imports as most required packages are not on test PyPI).
Assuming test PyPI worked, now upload to the main repository
Go to SCMData’s PyPI and check that the new release is as intended.
Test the install with
If you haven’t already, fork the SCMData conda feedstock. In your fork, add the feedstock upstream with
git remote add upstream https://github.com/conda-forge/scmdata-feedstock(
upstreamshould now appear in the output of
git remote -v)
Update your fork’s master to the upstream master with:
git checkout master
git fetch upstream
git reset --hard upstream/master
Create a new branch in the feedstock for the version you want to bump to.
version number in line 2 (don’t include the ‘v’ in the version tag)
the build number to zero in line 13 (you should only be here if releasing a new version)
sha256in line 10 (you can get the sha from SCMData’s PyPI by clicking on ‘Download files’ on the left and then clicking on ‘SHA256’ of the
.tar.gzfile to copy it to the clipboard)
git add .
git commit -m "Update to vX.Y.Z"
Make a PR into the SCMData conda feedstock
If the PR passes (give it at least 10 minutes to run all the CI), merge
Check https://anaconda.org/conda-forge/scmdata to double check that the version has increased (this can take a few minutes to update)
Push to repository
Finally, push the tags and commit to the repository
git push --tags
Why is there a
Makefile in a pure Python repository?
Whilst it may not be standard practice, a
Makefile is a simple way to automate general setup (environment setup in particular).
Hence we have one here which basically acts as a notes file for how to do all those little jobs which we often forget e.g. setting up environments, running tests (and making sure we’re in the right environment), building docs, setting up auxillary bits and pieces.