How to Contribute

Table of Contents

• Prerequisites
• Setting up and Knowing Your Development Workspace
  • Access the Code Base
  • VSCode Workspace
  • PyCharm Workspace
• Run Development Server
  • Initial Set Up
  • Run 'em

Prerequisites

The following tools are required:

• Git: For version control.
• Python (Version 3.8): For running the code.
• Poetry: For dependency management and packaging.

The following tools are suggested:

• VSCode or PyCharm (Free License for Students): For an ideal development workspace.
• Docker: For containerization in production.

Setting up and Knowing Your Development Workspace

Let's prepare an ideal workspace environment for us to code, test and deploy in.

Access the Code Base

First, fork this repository (if you're not part of the HTV development team). Then, clone the fork (or this repository) locally:

git clone https://github.com/<<<github-account>>>/hack-the-back.git

VSCode Workspace

Open up the cloned repository on VSCode. Now, you should notice a .vscode/ folder in the root directory. This contains all the default configurations that sets up an ideal workspace for you. Learn more below.

Extensions

The .vscode/extensions.json file contains all the recommended extensions that should be installed on VSCode. These recommended extensions should've popped up on the bottom right corner of your screen. Install them if you can.

Settings

The .vscode/settings.json file contains all the workspace settings for VSCode. Currently, it's set up such that you can easily format and lint your code when you save, as well as test your code when you need to.

Whenever changing VSCode settings for yourself, please be wary of making changes to .vscode/settings.json. Always double check any changes you made before committing.

Launch

The .vscode/launch.json file configures VSCode for you so you can easily run and debug the development server from VSCode. Learn more about debugging here.

PyCharm Workspace

Open up the cloned repository on PyCharm.

Any project-specific settings for PyCharm should not be committed to the main respository. This is why the .idea/ folder is in .gitignore.

Setting Python Interpreter

Open Preferences > Project: hack-the-back > Project Interpreter. Then select "Python 3.8 (hack-the-back)". This will set the python interpreter to Python 3.8 with the virtual environment. If you couldn't find the project interpreter, maybe you should run pipenv install in the PyCharm terminal first.

Launch Configurations

Learn more about adding configurations here, so that you can easily run and debug code like you would on VSCode.

Run Development Server

Initial Set Up

Follow the steps in order in the root of the project for the initial set up.

1. Set up virtual environment and install all dependencies (including dev dependencies)

   poetry config virtualenvs.in-project true
   poetry install

2. Spawn a shell within a virtual environment

   poetry shell

3. Generate a "SECRET_KEY" value

   # Enter the Django shell
   (hack-the-back) python manage.py shell
   >>> from django.core.management.utils import get_random_secret_key
   >>> print(get_random_secret_key())

4. Copy the random secret key that you just generated
5. Exit the Django shell

   exit()

Run 'em

Now, it's time to run the development server! 🤘

To do so, run SECRET_KEY=<<<paste-here>>> DEBUG=True python manage.py runserver. Open up a browser and go to http://127.0.0.1:8000/api/v1/graphql.

You can find a list of other Django administrative tasks here.