Attention
You are looking at outdated documentation for version 2.x. A newer version is available.
Development¶
This section describes how developers can contribute to the WsgiDAV project.
First off, thanks for taking the time to contribute!
There are many ways you can help:
- Send feedback:
Know a cool project that uses it, created a custom provider or have an interesting use case? Let us know in the forum . - Create issues for bugs or feature requests (see Bug Reports and Feature Requests below).
- Help others, by answering questions in the forum or on Stackoverflow.
- Improve this documentation.
- Fix bugs or propose features.
This small guideline may help taking the first steps.
Happy hacking :)
Bug Reports and Feature Requests¶
If you have encountered a problem with WsgiDAV or have an idea for a new feature, please submit it to the issue tracker on GitHub.
Note
The issue tracker is for bugs and feature requests. Please use the Q&A forum or Stackoverflow to ask questions.
Use the search function to find existing issues if any. If you have additional information, add a comment there instead of creating a new issue.
If it’s a bug report:
- Carefully describe the required steps to reproduce the failure.
- Give additional information about the server: (OS version, WsgiDAV version, WSGI server setup)? Which settings are enabled (configuration file)?
- What client are you using (OS, client software and -version)?
- What output do you see on the console or log files?
- Maybe attach a patch file or describe a potential fix?
If it’s a feature request:
- What are you trying to accomplish?
- Why is this a cool feature? Give use cases.
- Can you propose a specification? Are there similar implementations in other projects? Add references or screenshots if you have some. Remember that the general API must stay generic, extensible, and consistent. How will this interfere with existing API and functionality? Does it play well with the other extensions?
Contributing Code¶
Note
Please open (or refer to) an issue, even if you provide a pull request. It will be useful to discuss different approaches or upcoming related problems.
The recommended way for new contributors to submit code to WsgiDAV is to fork the repository on GitHub and then submit a pull request after committing the changes. The pull request will then need to be approved before it is merged.
- Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
- Fork the repository on GitHub.
- Clone the repo to your local computer
- Setup the project for development
- Create and activate your feature branch
- Hack, Hack, Hack
- Test, Test, Test
- Send a pull request and bug the maintainer until it gets merged and published.
Note
Don’t mix different topics in a single commit or issue. Instead submit a new pull request (and even create separate branches as apropriate).
Setup for Development¶
Fork the Repository¶
Create an account on GitHub.
Fork the main WsgiDAV repository (mar10/wsgidav) using the GitHub interface.
Clone your forked repository to your machine.
git clone https://github.com/YOUR_USERNAME/wsgidav cd wsgidav
Create and activate a new working branch. Choose any name you like.
git checkout -b feature-xyz
Create and Activate a Virtual Environment¶
Virtual environments allow us to develop and test in a sandbox, without affecting our
system othwerwise.
We need Python 2.7,
Python 3.4+,
and pip on our system.
If you want to run tests on all supported platforms, install Python 2.7, 3.4, 3.5, and 3.6.
On Linux/OS X, we recommend to use pipenv to activate a virtual environment:
$ cd /path/to/wsgidav
$ pipenv shell
bash-3.2$
Note: On Ubuntu you additionally may have to install apt-get install python3-venv
.
Alternatively (especially on Windows), use virtualenv
to create and activate the virtual environment.
For example using Python’s builtin venv
(instead of virtualenvwrapper
)
in a Windows PowerShell:
> cd /path/wsgidav
> py -3.6 -m venv c:\env\wsgidav_py36
> c:\env\wsgidav_py36\Scripts\Activate.ps1
(wsgidav_py36) $
Install Requirements¶
Now that the new environment exists and is activated, we can setup the requirements:
$ pip install -r requirements-dev.txt
and install wsgidav to run from source code:
$ pip install -e .
If everything is cool, this code should now run:
$ wsgidav --version
$ 2.3.1
The test suite should run as well:
$ tox
Hack, Hack, Hack¶
Test, Test, Test¶
Testing is best done through tox
, which provides a number of targets and
allows testing against multiple different Python environments:
To run all unit tests on all suppprted Python versions inclusive flake8 style checks and code coverage:
$ tox
To run unit tests for a specific Python version, such as 3.6:
$ tox -e py36
To run selective tests, ww can call
py.test
directly, e.g.:$ py.test -ra wsgidav tests/test_util.py
To list all possible targets (available commands):
$ tox -av
To build the Sphinx documentation:
$ tox -e docs
Gain additional Kudos by first adding a test that fails without your changes and passes
after they are applied.
New unit tests should be included in the tests
directory whenever possible.
Create a Pull Request¶
Make sure you have forked the original repository on GitHub and checked out the new fork to your computer as described above.
Create and activate your feature branch (
git checkout -b my-new-feature
).Commit your changes (git commit -am “Added some cool feature”).
Push to the branch (git push origin my-new-feature).
Create a new Pull Request on GitHub.
Please add a bullet point to
../../CHANGELOG.md
if the fix or feature is not trivial (small doc updates, typo fixes). Then commit:git commit -m '#42: Add useful new feature that does this.'
GitHub recognizes certain phrases that can be used to automatically update the issue tracker.
For example:
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
would close issue #42.
Wait for a core developer to review your changes.