diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 64 |
1 files changed, 38 insertions, 26 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bad2ccd..e93dab2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,7 @@ If you would like to fix something in `dateutil` - improvements to documentatio The most important thing to include in your pull request are *tests* - please write one or more tests to cover the behavior you intend your patch to improve. Ideally, tests would use only the public interface - try to get 100% difference coverage using only supported behavior of the API. #### Changelog -To keep users abreast of the changes to the module and to give proper credit, `dateutil` maintains a changelog, which is managed by [towncrier](https://github.com/hawkowl/towncrier). To add a changelog entry, make a new file called `<issue_no>.<type>.rst`, where `<issue_no>` is the number of the PR you've just made (it's easiest to add the changelog *after* you've created the PR so you'll have this number), and `<type>` is one of the following types: +To keep users abreast of the changes to the module and to give proper credit, `dateutil` maintains a changelog, which is managed by [towncrier](https://github.com/hawkowl/towncrier). To add a changelog entry, make a new file called `<issue_no>.<type>.rst` in the `changelog.d` directory, where `<issue_no>` is the number of the PR you've just made (it's easiest to add the changelog *after* you've created the PR so you'll have this number), and `<type>` is one of the following types: - `feature`: A new feature, (e.g. a new function, method, attribute, etc) - `bugfix`: A fix to a bug @@ -59,42 +59,54 @@ Starting December 1, 2017, all contributions will be assumed to be released unde All contributions before December 1, 2017 except those explicitly relicensed, are only under the 3-clause BSD license. -## Building and releasing - -When you get the source, it does not contain the internal zoneinfo -database. To get (and update) the database, run the updatezinfo.py script. Make sure -that the zic command is in your path, and that you have network connectivity -to get the latest timezone information from IANA, or from [our mirror of the -IANA database](https://dateutil.github.io/tzdata/). ## Development Setup -Install the the dependencies for running the test suite using `pip` or `conda`. +### Using a virtual environment -### pip +It is advisable to work in a virtual environment for development of `dateutil`. This can be done using [virtualenv](https://virtualenv.pypa.io): -Run the following commands to create a [virtual environment](https://virtualenv.pypa.io) with all dependencies installed: +```bash +python -m virtualenv .venv # Create virtual environment in .venv directory +source .venv/bin/activate # Activate the virtual environment +``` - python -m virtualenv .venv # Create virtual environment in .venv directory - . .venv/bin/activate # Activate the virtual environment - pip install -r requirements.txt # Install the dependencies +Alternatively you can create a [conda environment](https://conda.io/docs/user-guide/tasks/manage-environments.html): -### conda +```bash +conda create -n dateutil # Create a conda environment +# conda create -n dateutil python=3.6 # Or specify a version +source activate dateutil # Activate the conda environment +``` -Run the following commands to create a [conda environment](https://conda.io) with all dependencies installed: +Once your virtual environment is created, install the library in development mode: - conda create -n dateutil # Create a conda environment - # conda create -n dateutil python=3.6 # or specify a version - source activate dateutil # Activate the conda environment - pip install -r requirements.txt # Install the dependencies +```bash +pip install -e . +``` + +This will allow scripts run in your virtual environment to use the version of `dateutil` in your local directory. If you also want to run the tests in your local directory, install the test dependencies: + +```bash +pip install -r requirements-dev.txt +``` ## Testing -dateutil has a comprehensive test suite, which can be run simply by running -`python -m pytest` in the project root. Note that if you don't have the internal -zoneinfo database, some tests will fail. Apart from that, all tests should pass. +The best way to test `dateutil` is to run `tox`. By default, `tox` will test against all supported versions of Python installed on your system. To limit the number of tests, run a specific subset of environments. For example, to run only on Python 2.7 and Python 3.6: + +```bash +tox -e py27,py36 +``` + +You can also pass arguments to `pytest` through `tox` by placing them after `--`: + +```bash +tox -e py36 -- -m tzstr +``` + +This will pass the `-m tzstr` parameter to `pytest`, running only the tests with the `tzstr` mark. -To easily test dateutil against all supported Python versions, you can use -[tox](https://tox.readthedocs.io/en/latest/). +The tests can also be run directly by running `pytest` or `python -m pytest` in the root directory. This will be likely be less thorough but is often faster and is a good first pass to check your changes. -All GitHub pull requests are automatically tested using travis and appveyor. +All GitHub pull requests are automatically tested using [Travis](https://travis-ci.org/dateutil/dateutil/) and [Appveyor](https://ci.appveyor.com/project/dateutil/dateutil). |