Bug reports and pull requests to fix issues are always welcome, as are contributions to the built-in documentation.
If adding features, or making changes, it is recommended to update or add tests
and assertions to the appropriate test case class in
ensure code coverage. If the change(s) fix a bug, please add assertions that
reproduce the bug along with code changes themselves, and include the GitHub
issue number in the commit message.
Next, install Python dependencies for building and publishing as well as testing locally:
pip install -r requirements.txt pip install -r requirements-publish.txt
Running Unit Tests¶
Assuming that all dependencies are installed, running
the root path of the repository will run the unit test suite:
.rst files in
sphinx/source are where most of the documentation
lives. To rebuild the HTML documentation from the source, run:
To force a rebuild, run
touch CHANGELOG.rst first.
Releasing a New Version¶
You will first need valid user accounts on both
that have the “Maintainer” role on the project, as well as the requirements
installed (see above).
It is strongly recommended that you use an API token to upload new releases to PyPI.
Perform end-to-end publish and installation testing¶
To test publishing and installing from the package index, first make sure you
have a valid user account on
test.pypi.org that has publisher access to the
project as on
Note, once a release is uploaded, it is no longer possible to upload a release
with the same version number, even if that release is deleted. For that reason,
it is a good idea to first add a suffix, i.e.
setup.py while testing.
To perform end-to-end tests, run the following, entering credentials for
test.pypi.org when prompted:
The make target
testpublish performs the following:
Build the Python egg in
Upload the new library to
Test-install the library from
test.pypi.orginto a temporary Python virtualenv that does not already have the library installed, to test installing for the first time
Tests-install the library from
test.pypi.orginto a temporary Python virtualenv where the library is already installed, to test upgrading
If any errors are encountered, the script should immediately exit. Errors
should be investigated and mitigated before publishing. To test again,
__version__ so that it counts as a new release
and gets uploaded, and set it to the desired version before the actual
Merge changes and tag¶
A pull request for releasing a new version should be created, which along with the functional changes should also include at least:
An update to the changelog, where all items corresponding to community contributions end with (in parentheses) the GitHub user handle of the contributor, a slash, and a link to the pull request (see CHANGELOG.rst for preexisting examples).
A change in the version number in both setup.py and pdpyras.py, to a new version that follows Semantic Versioning.
Rebuilt HTML documentation
The HTML documentation can be rebuilt with the
docs make target:
After rebuilding the documentation, it can then be viewed by opening the file
docs/index.html in a web browser. Including rebuilt documentation helps
reviewers by not requiring them to have the documentation-building tools
Once the pull request is approved, merge. Then (locally) checkout main and tag:
git checkout main && \ git pull origin main && \ git tag "v$(python -c 'from pdpyras import __version__; print(__version__)')" && \ git push --tags origin main
Once the changes are merged and tagged, make sure your local repository clone
main branch checked out at the latest available commit, and the
local file tree is clean (has no uncommitted changes). Then run:
When prompted, enter
__token__ as your username and your API token as the password.
Finally, create a new release, and fill in some details:
Select “Choose a tag” and select the new latest tag.
If a new patch version is being released, update the existing release for that major and minor version.
Name the release after the major and minor version, i.e. 5.1, and very brief summary of changes.
Compose a description from the pull requests whose changes are included.