Skip to content

Latest commit

 

History

History
169 lines (103 loc) · 4.21 KB

CONTRIBUTING.md

File metadata and controls

169 lines (103 loc) · 4.21 KB
Raw

Contributing

We welcome many types of contributions, such as the following

  • ideas
  • bug reports
  • code
  • design
  • community development
  • outreach
  • project management

Contributing code

In order to contribute code, you will need to run the project on your local computer.

Prerequesites

Make sure you have installed the Poetry package manager before continuing onward in this developer guide.

CLA

Please sign our Contributor License Agreement prior to submitting any code.

Choose an issue

⚠️ Generally, we will not review pull requests unless they are associated with an issue that has been claimed by the author of the pull request.

Before writing any code, please choose or open an issue. If an issue exists, add a comment to claim that issue. If no related issue exists, create one and claim it.

Clone the code

You can download or clone this repository directly from GitHub, using a command line or GitHub Desktop.

Environment variables

To run this project locally, you need the following environment variable defined, such by creating a .env file with the following contents.

DJANGO_DEBUG=True

We can automatically set the environment variables from the .env file when activating the Poetry shell by installing the Poetry dotenv plugin.

Install the dependencies

Once you have the project cloned, you can install the project dependencies by running the following command from within the project root directory.

poetry install

Activate the virtual environment

Once the dependencies are installed, activate the virtual environment with the following command.

poetry shell

Change into the project/ subfolter

The following commands should be run from within the project/ subfolder of this repository. Use your command line tool to change directory into project/.

Run database migrations

Initialize and migrate the project database with the following command.

python manage.py migrate

Run the project

Create a super-user so you can log into the project.

python manage.py createsuperuser

Run the server

Run the project with the following command.

python manage.py runserver

Access the project in your web browser

Once the previous steps are complete and the server is running, visit the following URL in your web browser.

See our .editorConfig file

We use a .editorConfig to keep coding styles consistant between our different developers. See https://editorconfig.org/ for more information.

Test things out and contribute

Now that the project is running, you can try things out and consider how you would like to contribute! :-)

Testing

Generate test coverage

Run the following command from within the project/ directory to generate a test coverage report.

coverage run --source='.' manage.py test

View the coverage report with the following command.

coverage report

Troubleshooting

Resolving conflicts in poetry.lock

Whenever there are simultaneous changes to our project dependencies, there is a high likelihood of conflicts in poetry.lock. This issue is not unique to our project and likely happens in every Poetry project with multiple developers.

First sync your fork of the repository to keep it up-to-date with upstream.

  1. Checkout to the main branch
git checkout main
  1. Update main
git pull
  1. Checkout to your working branch
git checkout your-branch
  1. Merge main branch into your working branch
git merge main

At this point, you may get a conflict in poetry.lock. Here are some of the methods you can use to resolve the conflict:

Method-1

In order to get poetry.lock to look like it does in main, you can do the following:

git checkout --theirs poetry.lock
poetry lock --no-update

Method-2

  1. Delete the poetry.lock file
  2. Re-generate the poetry.lock file by running:
poetry lock