-
Marc Troelitzsch authoredMarc Troelitzsch authored
Development
Mwclient development is coordinated at https://github.com/mwclient/mwclient. Patches are very welcome. If there's something you want to discuss first, we have a Gitter chatroom.
Development environment
If you plan to submit a pull request, you should first fork the mwclient repo on GitHub, then check out the original repository and configure your fork as a remote:
$ git clone https://github.com/mwclient/mwclient.git
$ cd mwclient
$ git remote add fork git@github.com:MYUSERNAME/mwclient.git
You can then use pip to do an "editable" install so that your edits will be immediately available for (both interactive and automated) testing:
$ pip install -e .
Create a new branch for your changes:
$ git checkout -b my-branch
Test suite
mwclient ships with a test suite based on pytest. While it's far from complete, it can sometimes alert you if you break things.
To run the test suite, you can use tox. Tox will create a virtual environment for each Python version you want to test with, install the dependencies, and run the tests.
$ pip install tox
$ tox
If you want to run the tests for a single Python version, you can do so by specifying the Python version, e.g. to run the tests for Python 3.9:
$ tox -e py39
Alternatively, you can run the tests directly with pytest:
$ pip install -e '.[testing]'
$ py.test
There is a container-based integration test suite which is not run by default as it requires docker or podman, is a little slow, and needs to do ~3G of network transfer when first run (to download the mediawiki container images). It is run as part of CI. To run it locally, make sure you have docker or podman installed, then with tox, do:
$ tox -e integration
Or with pytest, do:
$ py.test test/integration.py
If you would like to expand the test suite by adding more tests, please go ahead!
Updating/expanding the documentation
Documentation consists of both a manually compiled user guide
(under docs/user
) and a reference guide generated from the docstrings,
using Sphinx autodoc with the napoleon extension.
Documentation is built automatically on ReadTheDocs
after each commit.
To build the documentation locally for testing:
$ pip install -e '.[docs]'
$ cd docs
$ make html
When writing docstrings, try to adhere to the Google style.
Making a pull request
Make sure to run tests before committing. When it comes to the commit message, there's no specific requirements for the format, but try to explain your changes in a clear and concise manner.
If it's been some time since you forked, please consider rebasing your branch on the main master branch to ease merging:
$ git rebase master
When it is ready, push your branch to your remote:
$ git push -u fork my-branch
Then you can open a pull request on GitHub. You should see a URL to do this when you push your branch. Tests will be automatically run on your pull request via GitHub Actions.
Making a release
These instructions are for maintainers of the project.
To cut a release, ensure CHANGELOG.md
is updated, then use
bump-my-version:
$ pip install bump-my-version
$ bump-my-version bump major|minor|patch
Then check the commit looks correct and is tagged vX.Y.Z, and push. The
.github/workflows/release.yml
action will publish to PyPI.