Skip to content

Latest commit

 

History

History
129 lines (99 loc) · 7.87 KB

CONTRIBUTING.md

File metadata and controls

129 lines (99 loc) · 7.87 KB
Raw

LevEchad

Thank you for contributing to the LevEchad system! 🔥

To improve the code quality and consistency across the codebase, we have some guidelines that we require our contributors to follow.

Getting Started

See the README file for more information on setting up the local backend development environment.

Codebase Walkthrough

We have separated frontend and backend repositories and servers - this means that the backend serves an API that the frontends can interface with. We currently have three repositories for this project:

  • levechad-backend - the Django backend. Serves the old client and server apps, which contain the models and the soon-to-be obsolete views, and the new api app, giving a REST API to the frontends.
  • levechad-frontend-vue - a Vue.js-based frontend. This will serve as the main frontend (until levechad-frontend is in production, see below) that contains the Hamal interface and the help request interface. In the meantime it also contains the registration process for volunteers, but this is temporary until levechad-frontend is in production - more on this below.
  • levechad-frontend - a React-based frontend, that in the future will become a "volunteer portal" where volunteers can log in, manage their missions, etc. This will live alongside the levechad-frontend-vue repository and allows us to extend this feature in the future.

The plan is to first have levechad-frontend-vue in production with the volunteer registration process, and only after that the Volunteer Portal will be in production and the registration process could be removed from levechad-frontend-vue. This allows us to achieve a fully functioning system as soon as possible.

The old system consists of the client and server apps (at URLs /client and /server, respectively), and has no frontend - Django serves the pages itself.

  • The client app is the system for the users, containing help request views, volunteer forms, etc. and all of the models.
  • The server app is only accessible to the LevEchad Hamal and all the view requires login, and is used to manage the volunteers & help requests.

We currently only maintain the old system for bug-fixes (that may apply to both the new and old systems). Currently we don't cleanup the Django frontend-related code (views, template) as it will be removed in the future in favor of the new frontend.

The new system starts with the api app, which serves the REST API using Django REST framework that the new frontend can interface with. This also has temporary dependencies to the client app (because the models are there) until the old system will be phased out completely. This will only serve an API to future frontends.

Currently we support both systems, as the new system is currently being built and is still not in production.

Fixing issues

  • When looking for missions, you can choose from the list of issues in our repo. It is also recommended to look at the projects, which are GitHub's Kanban Boards.
    • If you have an idea for an issue that's not listed, refer to the Creating issues section of this document.
  • Make sure to assign yourself to the issue you're working on, so two people won't work on the same thing by accident.
  • Branch from develop, and when you're finished, submit a PR (more on this below).

Branching

  • We do not push to develop (the stable development branch) or master (the releases branch) directly - this only happens through approved pull requests.

  • When creating an issue, make sure to branch from develop. Name your branch like so:

    issue/<issue-number>-<short-description>
# For example, we could name the branch of issue #123 titled "Add S3 integration to volunteer certificate image caching":
issue/123-cache-certificates-on-s3

  • Create the branch on the original repo, don't fork - if you need permissions as a returning contributor, contact one of the admins (including @astar26 and @stavlocker).

    • "Wandering contributors" that are not part of the contribution team can fork this repo and suggest changes as part of the open-sourced nature of the repo.

  • Make as little commits as you can (preferably one before CR, and one for each CR cycle), and keep the titles concise.

  • When finished, create a pull request (PR) to the develop branch. Remember to assign yourself to the PR. Also make sure to link the issue to the PR.

Pull Requests (Answering Code Reviews)

After creating a PR, you must answer the code review (CR) given. There must be an approving reviewer on a PR to merge it to the target branch.

  • The reviewer is not expected to test that your code works (although they may). You must do this before submitting any changes.
  • Make sure to address all the comments in your CR, by fixing them or commenting why you think they shouldn't be done.
  • You will not be able to merge to the traget branch (usually develop) before you fix all the conflicts by merging from the target branch to your branch. GitHub also shows if there are conflicts at the bottom of the pull request page.
  • When your PR is merged/closed, make sure to close the original issue.

Django migrations & dependencies

  • When changing models in Django, you must run the Django command makemigrations, to create the migration files later applied on the personal development DBs and the production DB. Use migrate to apply any unapplied migration files.

  • When moving between branches, you want to keep your local database adjusted to the migrations you currently have. If you're on a branch with new migrations and you want to switch branches, make sure to undo your migrations before switching:

    python3 manage.py migrate client <base-migration-name>

    To install new python dependencies added to the project:

    pip install -r requirements.txt

Migration conflicts

Sometimes after submitting a PR with migrations, other migrations get merged into develop. When you will merge from develop to you branch this will cause in two "leaf" migrations and running migrate will fail. In order to fix this, revert to the base migration (the latest migration you created your migrations on top of), delete the migration(s) you reverted, and re-migrate:

# Revert to base migration (<base-migration-name> is the name of the migration file without the extension):
python3 manage.py migrate client <base-migration-name>
# Delete the migrations reverted...
# Re-migrate:
python3 manage.py makemigrations
python3 manage.py migrate

More complicated conflicts may need special resolving, but the steps above are for the common case of conflicts.

Coding Guidelines

  • Make sure to use proper English throughout your code.
  • Follow the PEP-8 conventions.
  • Keep it DRY (Don't Repeat Yourself) - avoid code duplication. If you think a new module needs to be created for a certain functionality, create it.
    • If this requires major cleanup/refactor on the old system side (see Codebase Walkthrough above) you might want to reconsider. If you're unsure - just ask.
  • If there are major changes to the current project structure you wish to make, it's best to talk to one of the admins beforehand.
  • Wherever you can, write text in English and use the Django translation system (gettext) to translate to Hebrew (see #244 for backwards-changing).

Creating issues

  • Make sure to follow the issue template - make sure your issue isn't a duplicate and that it is clear & descriptive.
  • Issues shouldn't be questions - if you have a question, feel free to ask in the contribution team's group, or one of the admins.