Skip to content

Latest commit

 

History

History
167 lines (121 loc) · 6.82 KB

CONTRIBUTING.md

File metadata and controls

167 lines (121 loc) · 6.82 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.

  • 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

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.

  • 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.