Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Report bugs at https://github.com/time-link/timelink-py/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.
Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
Timelink Python package could always use more documentation, whether as part of the official Timelink Python package docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/time-link/timelink-py/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 :)
Ready to contribute? Here's how to set up timelink-py for local development.
Fork the timelink-py repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/timelink-py.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv timelink $ cd timelink/ $ python setup.py develop
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
$ flake8 timelink tests $ python setup.py test or pytest $ tox
To get flake8 and tox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
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. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
- The pull request should work for Python 3.10, 3.11 and for PyPy. Check https://app.travis-ci.com/github/time-link/timelink-py/pull_requests and make sure that the tests pass for all supported Python versions.
A reminder for the maintainers on how to deploy.
The Timelink package used as a template the cookiecutter-pypackage.
Check the documentation at https://github.com/audreyfeldroy/cookiecutter-pypackage on how to install various tools used.
Check the release procedure documentation at https://cookiecutter-pypackage.readthedocs.io/en/latest/travis_pypi_setup.html
Install development requirements with
pip install -r requirements_dev.txt
If using tox to test with different versions of Python then you need to have the various Python interpreters installed.
The tox.ini file specifies which version of Python will be used for tests. pyenv is used to install the different versions.
pyenv install 3.10 # for each version
On MacOS you may get a zlib related error while installing Python versions with pyenv. Check https://stackoverflow.com/questions/50036091/pyenv-zlib-error-on-macos
The solution for us was:
brew install zlib
export LDFLAGS="-L/usr/local/opt/zlib/lib"
export CPPFLAGS="-I/usr/local/opt/zlib/include"
pyenv install 3.7.2
If tox complains of not finding the different Python version you need to reinstall tox after installing locally the various versions. See https://brandonrozek.com/blog/pyenvtox/
Example:
pip install tox
Also, if tox complains of not finding the various Python versions then try: * check that the versions are installed with pyenv versions` * if not install with pyenv e.g. pyenv install 3.11 * check that the version are available locally with pyenv local 3.10 3.11 [...] * run tox with the -e option to specify the environment.
Alternatively try to run tox --recreate to recreate the virtual environments.
tox -e py311 # run tests with Python 3.11
The target test-all triggers the test in the various versions.
To release a new version: tox --recreate .. code-block:: bash
make lint # check code style make test # run the local test suite make coverage # check test coverage make test-all # test on different versions of python make docs # update the documentation git status # check if everything is commited bump2version [major|minor|patch] # update version git push git push --tags # will trigger travis build and deploy
Travis will then deploy to PyPI if tests pass.
If Travis fails to deploy to PyPI, try "make release" locally.
Note that errors in package description in setup.py can prevent deployment to PyPI. This happens mainly with markup problems in HISTORY.rst. See pypi/warehouse#5890
"make release" will do twine check dist/* to check for errors.
To run a subset of tests:
$ pytest tests/test_mhk_utilities.py
To run a subset of tests with tox:
$ tox -- tests/test_mhk_utilities.py
Tests related to the existence of a MHK installation
Some tests are related to the existence of a MHK instalation on the same machine. The tests check for the existence of the file .mhk in the user home directory (~/.mhk).
If MHK is installed rename ~/.mhk to run tests as if MHK is not present:
$ mv ~/.mhk ~/.mhk_copy $ make test-allOnce tests are run rename back to the original name:
$ mv ~/.mhk_copy ~/.mhk $ make test-allWe also use [nbval](https://nbval.readthedocs.io/en/latest/) to test the notebooks. To run the tests on the notebooks:
$ py.test --nbval tests/timelink-home/projects/test-project/*
Tha make target "test" activates both code and notebook tests. Currently the notebooks are not tested on different versions of Python (no tox integration)
To pass code style check
flake8 is used for code-style check, with the flake8-bugbear extension for extra checks, and a line length of 88 chars.
We recommend using black to reformat your code so that it passes the flake8 checks.
flake8 settings in setup.cfg ensure compatibility with black code style.
To format and check the code:
$ black timelink $ make lint
To generate updated documentation use make docs
.
The generation is available at https://timelink-py.readthedocs.io/
Documentation is written ReadTheDocs, using the reStructeredText format and the Sphinx formatter. See:
For docstrings in source code we use the Google style guide, which is more legible during code editing than ReStructured text.
Source code docstring in the Google format will be automatically rendered by
make docs
. For details on how the docstring will be integrated with the
rest of the documention see:
After doing make docs
type:
python -m sphinx.ext.intersphinx docs/_build/html/objects.inv
List commits since the last version:
$ git log $(git describe --tags --abbrev=0)..HEAD --oneline
or, for specific versions:
$ git log v0.2.9..v0.3.0 --oneline