Skip to content

Latest commit

 

History

History
216 lines (154 loc) · 8.18 KB

CONTRIBUTING.md

File metadata and controls

216 lines (154 loc) · 8.18 KB
Raw

Contributing

You are more than welcome to contribute to the system. This guide documents how to create a local development setup, the tools/frameworks used, and the steps required to get a pull request approved.

Getting a local setup

  • Installing Docker: Download and install Docker Compose. If you use Ubuntu 18.04 (LTS), you can use this guide to set up Docker.

  • Fork this repo to your own account.

  • The setup adheres to the twelve-factor-app principles. To get a local development configuration, copy the file .env.example to .env

  • Run docker compose up to start your local system.
    (If on Apple Silicon machine, run docker compose -f docker-compose.yml -f docker-compose.arm64.yml up --build)

  • Run docker compose run web ./manage.py get_live_data to download public data and insert it into your local database.

  • To get some dummy members, families, etc. you can use the factories to create them.

        docker compose run web ./manage.py shell
    from members.tests.factories import MemberFactory
    MemberFactory.create_batch(20)

    Creates 20 members with associated families, departments, etc. Note that the data generated by the factories is not entirely consistent with the real world. For instance each member belongs to their own department.

  • To create a super user for the admin interface you can run docker compose run web ./manage.py createsuperuser

  • A pgAdmin container is configured as part of Docker Compose, and can be accessed on http://localhost:5050. Log in with credentials [email protected]/admin. Connection to database has been configured in pgadmin/servers.json file, you just need to provide password to database when asked (can be found in your .env file)

  • To enable auto formatting with black on Linux: copy the pre-commit file into the .git/hooks directory

    cp pre-commit .git/hooks

    and then give it executeable permissions

    chmod +x .git/hooks/pre-commit

    Note: This only works on Unix. (MacOS or Linux) And only if you have black installed on python3 with

    python3 -m pip install black

NOTE: If using linux with SELINUX you may need to add/change the following to your docker-compose.yml

services:
  web:
      privileged: true <-- add this
      ...

Primary Frameworks/Systems used

  • Django: The base web framework used. The link is to their great tutorial which takes an hour or two to complete.

  • Docker: We use docker compose to setup database, environment and dependencies. The following commands is all that's required to work on the system.

    • docker compose build -- Builds the system.
    • docker compose up -- Starts the systems.
    • docker compose down && docker volume rm backend_database -- Deletes your local database
    • docker compose run web command -- Replace command with what you want to run in the system.

  • SASS: CSS files belong in members/static/members/sass, store it as either plain .css files or .scss files. Compilation happens during each build, during local development run the following command in a separate terminal:

    docker compose run web node_modules/.bin/sass --watch members/static/members/sass/main.scss members/static/members/css/main.css

    It will compile SASS when you save a file. If you create a new .scss file remember to add it to main.scss.

  • HTML documentation Shows the css classes that can used for formatting.

  • Selenium: runs the functional tests. To run a specific test run

        docker compose run web ./manage.py test members.tests.test_functional.test_create_family

    where the name of your tests replaces the last part.

  • Unit tests: runs the unittests. You run the unit tests the same way as the selenium tests. To run a specific test run

        docker compose run web ./manage.py test members.tests.test_dump_data

    where the name of your tests replaces the last part.

  • Quickpay: We use QuickPay for payments, .env.example contains a test api key. Quickpay has a series of cards that can be used for testing

Local development

Pragmatic development is to use docker for database and run server and/or tests locally

  • Install Poetry

  • Install python dependencies: poetry install

  • Install npm

  • Install npm dependencies: npm install

  • Copy the sample environment file: cp .env.example .env

  • boot the database with docker compose start database

  • boot a selenium docker with docker run -it -p 4444:4444 -p 7900:7900 --network="host" -v /dev/shm:/dev/shm selenium/standalone-chrome

  • start the virtual env shell and work from there further on with poetry shell

  • Run sass: ./node_modules/.bin/sass members/static/members/sass/main.scss

  • Run collectstatic: ./manage.py collectstatic --no-input --clear

  • Run the tests: ./manage.py test

From here on you can boot a development server and optionally populate it with some arbitrary data:

  • Boot development server : ``

You can load some sample data into the local development environment by starting the django console with ./manage.py shell and then

from members.tests.factories.member_factory import MemberFactory
MemberFactory.create_batch(20)

In the same console you can create a password for the first person, so you can login:

from members.models import Person
p = Person.objects.first()
p.user.set_password('test')
p.user.save() # store in DB
p.user.username # show login email

Creating a pull request

  1. Join our slack and introduce yourself in the medlemssystem_dev channel.
  2. Pick a card from either the backlog or to-do column on the project page.
  3. Open a draft pull request before writing any code. This ensures that the design discussion happens before the code and limits duplicate work.
  4. Help us specify the requirements specification.
  5. Code the features with tests, see the testing guide
  6. Run the entire test suite with: docker compose run web ./manage.py test
  7. Check that the following requirements are meet:
    • The code has tests, code without tests is not accepted. (Except for minimal CSS and text changes). Use the existing test as inspiration and the factories to create dummy data.
    • The code conforms to the black formatting rules. To format your code run docker compose run web black .. Consider looking for an editor integration.
    • The code passes flake8 checks.
  8. Submit the pull request.
  9. The backend is Heroku, we can use their "review apps" to create a temporary server for each pull request.

Deploying

See DEPLOYING.md for instructions on deploying to test, staging and production environments.