Contributing to wagtailmenus¶
Hey! First of all, thanks for considering to help out!
We welcome all support, whether on bug reports, code, reviews, tests, documentation, translations or just feature requests.
Using the issue tracker¶
The issue tracker is the preferred channel for bug reports, features requests and submitting pull requests. Please don’t use the issue tracker for support requests. If you need help with something that isn’t a bug, you can join our Wagtailmenus support group and ask your question there.
Please submit any new or improved translations (both .po and .mo files) as a new PR.
Contributing code changes via pull requests¶
If there are any open issues you think you can help with, please comment on the issue and state your intent to help. Or, if you have an idea for a feature you’d like to work on, raise it as an issue. Once a core contributor has responded and is happy for you to proceed with a solution, you should create your own fork of wagtailmenus, make the changes there. Before committing any changes, we highly recommend that you create a new branch, and keep all related changes within that same branch. When you’ve finished making your changes, and the tests are passing, you can then submit a pull request for review.
What your pull request should include¶
In order to be accepted/merged, your pull request will need to meet the following criteria:
Documentation updates to cover any new features or changes.
If you’re not in the list already, add a new line to
CONTRIBUTORS.md(under the ‘Contributors’ heading) with your name, company name, and an optional twitter handle / email address.
For all new features, please add additional unit tests to
wagtailmenus.tests, to test what you’ve written. Although the quality of unit tests is the most important thing (they should be readable, and test the correct thing / combination of things), code coverage is important too, so please ensure as many lines of your code as possible are accessed when the unit tests are run.
If you’d like a runnable Django project to help with development of wagtailmenus, follow these steps to get started. The development environment has
django-debug-toolbar and some other helpful packages installed to help you debug with your code as you develop:
In a Terminal window,
cdto the project’s root directory, and run:
python3 -m venv .venv pip install -e '.[development]' -U source .venv/bin/activate
Create a copy of the development settings:
cp wagtailmenus/settings/development.py.example wagtailmenus/settings/development.py
Create a copy of the development urls:
cp wagtailmenus/development/urls.py.example wagtailmenus/development/urls.py
manage.pyby copying the example provided:
cp manage.py.example manage.py
Run the migrate command to set up the database tables:
python manage.py migrate
To load some test data into the database, run:
python manage.py loaddata wagtailmenus/tests/fixtures/test.json
Create a new superuser that you can use to access the CMS:
python manage.py createsuperuser
Run the project using the standard Django command:
python manage.py runserver
Your local copies of
manage.py will be ignored by git when you push any changes, as will anything you add to the
Running the test suite¶
It’s important that any new code is tested before submitting. To quickly test code in your active development environment, you should first install all of the requirements by running:
source .venv/bin/activate pip install -e '.[testing]' -U
Then, run the following command to execute tests:
Or if you want to measure test coverage, run:
coverage run --source=wagtailmenus runtests.py coverage report
Testing in a single environment is a quick and easy way to identify obvious issues with your code. However, it’s important to test changes in other environments too, before they are submitted. In order to help with this, wagtailmenus is configured to use
tox for multi-environment tests. They take longer to complete, but running them is as simple as running:
You might find it easier to set up a Travis CI service integration for your fork in GitHub (look under Settings > Apps and integrations in GitHub’s web interface for your fork), and have Travis CI run tests whenever you commit changes. The test configuration files already present in the project should work for your fork too, making it a cinch to set up.
Building the documentation¶
First install the necessary requirements by running:
source .venv/bin/activate pip install -e '.[docs]' -U
docsdirectory to do documentation-related stuff:
Check for and correct any spelling errors raised by sphinx. If you’re on Windows, please see how to run make commands on Windows:
Check that the docs build okay, and look out for errors or warnings: