Developing django-uswds-forms¶
Important
This section is about developing django-uswds-forms itself, not using it in your Django project. For details on the latter, see the Quick start guide.
First, clone the git repository:
git clone https://github.com/18F/django-uswds-forms
Then create a virtualenv for the project and install development dependencies:
virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements-dev.txt
Then install django-uswds-forms in development mode:
python setup.py develop
You will also need to download PhantomJS
and put it somewhere on your PATH
, as it’s required by the
test suite.
Running the example gallery app¶
An example Django project provides a integration with django-uswds-forms by presenting a variety of examples alongside their source code. It can be used to manually ensure that everything works as expected.
To use it, run the following from the root of the repository:
cd example
python manage.py migrate
python manage.py runserver
At this point you should be able to visit the locally-hosted project.
Adding new examples¶
To add a new example to the gallery, run:
python manage.py startexample <example-slug>
Where <example-slug>
is a slug for your new example, e.g.
my_cool_example
. The output of the command will tell you
what to do next.
Note that certain kinds of tests are automatically run on all examples:
- A
GET
request is made on the example’s view, and its status code is expected to be 200. - The example is rendered with its Django and Jinja2 template, and both versions are expected to produce the same HTML.
- The example is analyzed by aXe and expected to produce no accessibility violations.
Enabling Jinja2 mode¶
By default, the example gallery app renders all its examples using their Django template source. However, the examples also need to work on Jinja2! To make sure that they do, you’ll want to run the app in Jinja2 mode, which can be done by setting the following environment variable prior to running the app:
export TEMPLATE_ENGINE=jinja2
Running tests¶
You can run all the tests with code coverage:
pytest
You can also ensure that there aren’t any linting errors:
flake8
To run all tests, linters, and other automated QA against all supported runtimes and dependencies, run:
tox
Writing documentation¶
If you want to work on documentation, you can run the development documentation server with:
python setup.py devdocs
Publishing a new release¶
See RELEASE.md for details on publishing a new release.