Technical Onboarding for Developers

Getting started

Follow these guides to get started with the project

1. How to build and run the project.
   • For experienced developers: fork and clone the project, then do this subsection to run it in docker
2. How to authenticate with Cognito and work with the API

Please post any problems in the slack channel so we can fix/improve the pages. Or better yet, help in fixing them yourself.

Quick links to resources

1. Project

   • Slack channel where we have ephemeral project discussions. Permanent discussions should be done in GitHub issues.
   • Code repository where we keep the code.
   • GH Pages Documentation where we keep code-related docs. This is synced to the current state of the main branch.
   • Wiki documentation where we keep project but not code-related documentation.
   • Project Board where we track the project's progress.

2. Design

   • Entity Relationship Diagram (ERD)
   • PD: Table and Field definitions - this spreadsheet has grown beyond its original scope and now contains data that will be imported into the DB.

Work to be done

Currently, we need to build out the database to support the VRMS project, as described in the temporary roadmap

We need help and have guides to do the following:

1. Create issues for creating new tables
2. Write code to create models and API endpoints

What issues to work on:

1. Model (table) creation

   1. There are good first issue issues in the Project board's Prioritized Backlog. What makes them "easy" is they are generally tables/models/that can stand alone, without relationships to other models.

   2. After finishing one of those, the next issue to work on might be a table/model that relates to your first one. These usually have a single relationship. See the ERD to see which one it is. For the language model, it would be the project_language_xref model.

   3. Another type of model comes with initial data. These are very similar to the good first issue issues except for the extra data that need to be coded in. There's a guide on how to add migration files for initial data to help in doing that.

   4. Lastly, there's the rest of the models.

2. Larger issues or groups of issues (epics)

   • Permissions implementation
   • Events schema redesign
   • Documentation (structure and content)
   • Deployment to AWS
   • Local self-sufficient setup (not relying on external services like cognito and S3)
   • Reference client for the backend

Development tools

For Windows, the best way is to install wsl and vscode in the order suggested here. Then install git from wsl.

1. Git
2. POSIX-style shell (bash is a common one)
   1. Linux and macOS already come with one
   2. Windows
      1. Install wsl or wsl2 with Ubuntu.
      2. Alternatively, install git with git-bash shell (can work, but not officially supported by this project)
3. VS Code (preferred because of the plugins below) or other code editor
   1. Plugins (for VS Code)
      1. Remote Development (or at least Remote - Containers) - allows Code to use the environment inside a docker container for discovering code issues. Otherwise, it will think all the django imports are missing.
      2. Pylance - python language support. Also supports black code formatter if it's installed
      3. Markdown Preview Enhanced - for previewing markdown, with support for diagrams, including mermaid and plantuml
      4. ShellCheck - lint for shell scripts
      5. hadolint - lint for Dockerfile
4. Docker (Docker Engine or Docker Desktop) and docker-compose
5. ModHeader browser plugin - for setting authentication header

Developer learning resources

• Python
  1. Very basic intro - DjangoGirls Python Intro
  2. Best practices - testdriven.io Python Guides
  3. Software architecture - Architecture Patterns with Python
  4. TDD and Django - Test-Driven Development with Python
• Django (just the models, not the templates)
  1. Very basic intro - DjangoGirls Django Tutorial
  2. Official tutorial - djangoproject.com tutorials
  3. Best practices - Hacksoft's Django style guide
• Django REST Framework
  1. Official project tutorial - django-rest-framework.org tutorials
  2. Best practices - Hacksoft's Django style guide APIs and Serializers