Obviously this project doesn't work without people adding contributions, preferably many people adding lots of little contributions frequently. The project is oriented towards contributions which add new apps or features, with the constitution mechanic aimed at making it harder to significantly alter existing code than to add new things. The constitution is also aimed at protecting the core purpose and philosophy of the site, not its functionality. There are innumerable ways to just break the deployment or delivery of the website and I humbly ask that you refrain from intentionally doing so. If I see a pull request which breaks the site, I will close it. Use this website as a playground for whatever project you have that you want to see hosted as long as Django can serve it; I'd love for this to serve people's random creations. That being said, there are plenty of contributions and additions you could make to the site itself, including this document. Regardless of how you choose contribute, as long as it is in good faith, I appreciate it.
Some ideas for contributions include:
- Adding a new django app
- Adding a new feature to an existing app
- Adding a new page
- Improving Documentation
- User Interface Enhancements
- Adding tests for existing code
- Providing translations
For larger changes, or changes to the dev or Docker containers, you should set up
Docker on your local machine. If you develop in a dev container, the .envs
directory, which is required by Docker to create the container images, will be copied
from .envs.template automatically. If you do not create a dev container, then before
you run the Docker containers you MUST copy the .envs.template directory to
.envs yourself. You can create the copy without overwriting any existing changes
you have made using this command:
$ cp -rn .envs.template/ .envs/
Once .envs exists, you can personalize any environment variables you need, such as
saving OAuth application credentials in .django. Remember to never
put sensitive information anywhere it might be added to source control!
- Docker; if you don't have it yet, follow the installation instructions.
- Docker Compose; refer to the official documentation for the installation guide.
- Pre-commit; refer to the official documentation for the pre-commit.
- Just (optional); to simplify running commands, install just.
The commands below assume you have just installed. If you don't, you can reference the
commands in the justfile directly.
Building the stack can take a while, especially the first time you run this command on your system:
$ just build
Before making a git commit, you must have installed pre-commit and then run:
$ pre-commit install
The first time the container is run it might take a while to get started, but subsequent runs should start quickly.
Open a terminal at the project root and run the following for to activate all services:
$ just up
The site should start and be accessible at http://localhost:8000/ and the documentation at http://localhost:9000.
To run a specific service and its dependencies, run:
$ just up <service_name>
To run a full stack without Celery, start django:
$ just up django
Shortcuts for all the management commands mentioned in the README are available in the justfile.
To see a list of all the available commands, run just without any arguments.
:obj:`democrasite.webiscite` needs webhooks to find out about events on
Github. Create a webhook in your fork of the repository, then generate a
secret key for your hook and store it in .envs/.local/.django (or your shell) as
GITHUB_WEBHOOK_SECRET so it matches the secret configured on GitHub.
To test your webhook, follow these instructions. (If you have a preferred tool for exposing your local server, feel free to replace smee with it.) If you are using smee, be sure to run:
$ smee --url WEBHOOK_PROXY_URL --path /hooks/github/ --port 8000
to set the correct port and path.
When a :class:`~democrasite.webiscite.models.Bill` passes, the corresponding pull
request is automatically merged into the main branch, and if code blocks from the
Constitution are moved, their locations are automatically updated in the remote
constitution.json. In order to test this functionality in your fork of the
repository, you will need to create a Github personal access token and include it in
your django environment file as GITHUB_TOKEN. Make sure it at least has write
access to your fork of the repository.
The easiest way to run tests is by running just test. This will run the tests from
the django Docker service so they have access to Postgres. To run the tests in the
local environment, for example using the VSCode test runner, you must have PostgreSQL
installed on your computer, and you must set the environment variable
DATABASE_URL=postgres:///democrasite. Django should automatically create a test
database for you when you run the tests.