Notes for developers of
All commands in this file assume you work in a virtual environment created with virtualenvwrapper as follows (please keep up to date!):
# pip install virtualenvwrapper # Add to .bashrc: # export WORKON_HOME=$HOME/.virtualenvs # source ~/.local/bin/virtualenvwrapper.sh # Where are my virtual envs stored? # echo $WORKON_HOME # Create environment using Python 3 #mkvirtualenv -p $(which python3) geoextent # Activate env workon geoextent # Deactivate env deactivate #cdvirtualenv #rmvirtualenv
In the environment created above, run
pip install -r requirements.txt
Install a matching version of gdal-python into the virtual environment:
gdal-config --version CPLUS_INCLUDE_PATH=/usr/include/gdal C_INCLUDE_PATH=/usr/include/gdal pip install gdal==`gdal-config --version`
For the installation to suceed you need the following system packages (on Debian/Ubuntu):
To install development requirements, run
pip install -r requirements-dev.txt
Either install the lib and run
pytest, or run
python -m pytest.
You can also run individual files:
pytest pytest tests/test_api.py
Build documentation locally¶
cd docs/ pip install -r requirements-docs.txt make html
Build documentation website¶
The deployed documentation website is built on Travis CI, see file
.travis.yml for details.
In short, an extra stage
build docs is executed only on the
master branch and not for pull requests.
pip install --upgrade setuptools wheel twine
Make sure that all tests work locally by running
and check the tests on Travis CI o2r-project/geoextent before continuing with the following tasks.
Bump version for release¶
Follow the Semantic Versioning specification to clearly mark changes as a new major version, minor changes, or patches.
The version number is centrally managed in the file
Update the changelog in file
docs/source/changelog.rst, use the sphinx-issues syntax for referring to pull requests and contributors for changes where appropriate.
Build distribution archive¶
See the PyPI documentation on generating a distribution archive, https://packaging.python.org/tutorials/packaging-projects/, for details.
# remove previous releases and builds rm dist/* rm -rf build *.egg-info python3 setup.py sdist bdist_wheel
Upload to test repository¶
First upload to the test repository and check everything is in order.
# upload with twine, make sure only one wheel is in dist/ twine upload --repository-url https://test.pypi.org/legacy/ dist/*
Check if the information on https://test.pypi.org/project/geoextent/ is correct. Then switch to a new Python environment or use a Python 3 container to get an “empty” setup. Install geoextent from TestPyPI and ensure the package is functional:
docker run --rm -it -v $(pwd)/tests/testdata/:/testdata python:3-buster /bin/bash # install system deps apt-get update apt-get install gdal-bin libgdal-dev libproj-dev libgeos-dev libspatialite-dev netcdf-bin # in the container, first install packages not on TestPyPI or where we need a specific version (you might have to manually identify the closest matching pygdal version pip install geojson pyproj pygdal==`gdal-config --version` pip install -i https://test.pypi.org/simple/ geoextent geoextent --help geoextent --version geoextent -b -t /testdata/geojson/muenster_ring_zeit.geojson geoextent -b -t /testdata/shapefile/gis_osm_buildings_a_free_1.shp
Alternatively, use Debian Testing container to try out a more recent version of GDAL which matches the current release of the GDAL package on PyPI:
docker run --rm -it -v $(pwd)/tests/testdata/:/testdata debian:testing # Python + PIP apt-get update apt-get install python3 python3-pip wget # System dependencies apt-get install gdal-bin libgdal-dev libproj-dev libgeos-dev pip install geojson pyproj pygdal==`gdal-config --version` pip install -i https://test.pypi.org/simple/ geoextent geoextent --help geoextent --version wget https://github.com/o2r-project/geoextent/blob/master/tests/testdata/tif/wf_100m_klas.tif geoextent -b wf_100m_klas.tif
Upload to PyPI¶
twine upload dist/*
Check if information on https://pypi.org/project/geoextent/ is all correct. Install the library from PyPI into a new environment, e.g., by reusing the container session from above, and check that everything works.
Add a version tag to the commit of the release and push it to the main repository. Go to GitHub and create a new release by using the “Draft a new release” button and using the just pushed tag. Releases are automatically stored on Zenodo - double-check that the release is also available on Zenodo