Contributing

Contributions are welcome, preferably via pull request. Check the github issues to see what needs work. Tagulous aims to be a comprehensive tagging solution, but try to keep new features from having a significant impact on people who won’t use them (eg tree support is optional).

When submitting UI changes, please aim to support the latest versions of Chrome, Firefox and Internet Explorer through progressive enhancement - users of old browsers must still be able to tag things, even if they don’t get all the bells and whistles.

Installing

The easiest way to work on Tagulous is to fork the project on github, then install it to a virtualenv:

virtualenv django-tagulous
cd django-tagulous
source bin/activate
pip install -e git+git@github.com:USERNAME/django-tagulous.git#egg=django-tagulous
pip install -r src/django-tagulous/requirements.test.txt

(replacing USERNAME with your username).

This will install the development dependencies too, and you’ll find the tagulous source ready for you to work on in the src folder of your virtualenv.

Testing

It is greatly appreciated when contributions come with unit tests.

Pytest is the test runner of choice:

pytest
pytest tests/test_file.py
pytest tests/test_file::TestClass::test_method

Use tox to run them on one or more supported versions:

tox [-e py39-django3.2]

To use a different database (mysql, postgres etc) use the environment variables DATABASE_ENGINE, DATABASE_NAME, DATABASE_USER, DATABASE_PASSWORD, DATABASE_HOST and DATABASE_PORT, eg:

DATABASE_ENGINE=pgsql DATABASE_NAME=tagulous_test [...] tox

Most Tagulous python modules have corresponding test modules, with test classes which subclass tests.lib.TagTestManager. They use test apps defined under the tests dir where required.

Run the javascript tests using Jasmine:

pip install jasmine
cd tests
jasmine
# open http://127.0.0.1:8888/ in your browser

Javascript tests are defined in tests/spec/javascripts/*.spec.js.

Code overview

Tag model fields start in tagulous/models/fields.py; when they are added to models, the models call the field’s contribute_to_class method, which adds the descriptors in tagulous/models/descriptors.py onto the model in their place. These descriptors act as getters and setters, channeling data to and from the managers in tagulous/models/managers.py.

Models which have tag fields are called tagged models. For tags to be fully supported in constructors, managers and querysets, those classes need to use the classes defined in tagulous/models/tagged.py as base classes. That file contains a class_prepared signal listener which tries to dynamically change the base classes of any models which contain tag fields.

Model fields take their arguments and store them in a TagOptions instance, defined in tagulous/models/options.py. Any initial tags in the options can be loaded into the database using the functions in tagulous/models/initial.py, which is the same code the initial_tags management command uses.

When a ModelForm is created for a model with a tag field, the model field’s formfield method is called. This creates a tag form field, defined in tagulous/forms.py, which is passed the TagOptions from the model. A tag form field can also be created directly on a plain form. Tag form fields in turn uses tag widgets (also in tagulous/forms.py) to render the field to HTML with the data from TagOptions.

Tag strings are parsed and rendered (tags joined back to a tag string) by the functions in tagulous/utils.py.

Everything for enhancing the admin site with support for tag fields is in tagulous/admin.py. It is in two sections; registration (which adds tag field functionality to a normal ModelAdmin, and replaces the widgets with tag widgets) and tag model admin (for managing tag models).