Skip to content

Development

Jump to bottom
Stefan Dworschak edited this page Oct 26, 2020 · 21 revisions

Development

Table of contents

  1. Forking the repo
  2. Development in Gitpod
  3. Environment setup
  4. Local setup - you will still need to go through some of the steps in the environment setup
    1. Required Software
    2. Setup with automated scripts
    3. Mac / Linux
    4. Windows
    5. What will it do?
    6. What will it not do?
    7. Where to continue?
  5. Data Representation
  6. Committing your changes
  7. Creating a Pull Request (PR)

Forking the repo - IMPORTANT!

Development in Gitpod

Please ensure development is done within a virtual environment, whether locally or on Gitpod.

Our current preference is to have contributors work directly in Gitpod, to avoid any possible implications that may arise from not using a virtual environment.

Working in Gitpod will give you access to a Cloud IDE with most of the environment already out of the box and will avoid you having to set up most of the environment locally.

If you choose to develop locally, you can see how to proceed here

Environment setup

For working in Gitpod, here's the series of steps to take in order to proceed with development:

  1. Create a .env file with the specified variables.
    • touch .env
    • View our example .env_sample file for reference.
  2. Install all requirements from the requirements.txt file:
    • pip3 install -r requirements.txt
  3. Make sure to checkout into an appropriate branch. Never develop onto the master branch.
    • git branch -a (view existing branches)
    • git checkout -b new_branch_name (create new branch)
    • git checkout branch_name (go to an existing branch)
  4. Ensure that you have both origin and upstream remotes on your forked project.
    • git remote -v (view the remotes)
  5. Pull any updates from the master upstream branch, onto your current branch:
    • git pull upstream master
  6. Launch the Django project:
    • python3 manage.py runserver
  7. The Django server should be running (either locally, or on Gitpod).
  8. When you run the Django server for the first time, it should create a new SQLite3 database file: db.sqlite3
  9. Next, you will need to make migrations to create the database schema:
    • CTRL+C (stop the app)
    • python3 manage.py makemigrations
    • python3 manage.py migrate
  10. Seed default data such as a standard adminuser and some additional development data:
    • scripts/seed.sh
  11. In order to access the Django Admin Panel, you must generate a superuser:
    • python3 manage.py createsuperuser
    • (assign your own admin username, email, and secure password)
  12. Launch the Django project once again:
    • python3 manage.py runserver

Local setup

Required Software

In order to run this project locally on your own system, you will need the following installed (as a bare minimum):

Setup with automated scripts

To simplify the following setup steps, the community has created automated setup scripts for Linux/Mac and Windows. Here is how you can execute them:

Mac / Linux

  1. Open Terminal
  2. Give execute permissions to file
chmod +x setup.sh
  1. Run the setup file
./setup.sh

Windows

Requirements for Windows

  • Python installed and added to path

Setup

  1. Open Powershell from the Windows menu (or right-click on the folder
  2. Navigate to the folder
  3. Run the file
setup.bat

What will this do?

  • Setup a virtual environment using pipenv
  • Copy and modify the .env (You still need to edit it and add your own SECRET_KEY)

What will it not do?

  • Create any branches for you
  • Setup any databases or run any migration commands.

Where to continue?

This will help with Issue: https://github.com/Code-Institute-Community/ci-hackathon-app/issues/70 and speed up development when using local IDE like VSCode.

If you experience any issues with the automated scripts, please raise a new issue here

Data Representation

Once the database migrations and superuser have been successfully completed, Django should migrate the existing migrations.py files from each app to configure the following schema:

Hackathon ERD

User (django.contrib.auth)

id: <IntegerField> (PK)
username: <CharField> (UNIQUE)
email: <CharField>
first_name: <CharField>
last_name: <CharField>
is_staff: <BooleanField>
is_superuser: <BooleanField>

Hackathon (models.Model)

id: <IntegerField> (PK)
created: <DateTimeField>
updated: <DateTimeField>
created_by: User (FK)
display_name: <CharField>
description: <TextField>
start_date: <DateTimeField>
end_date: <DateTimeField>
awards: HackAwardCategory (FK)
teams: HackTeam (FK)
judges: User (FK)
organizer: User (FK)

HackTeam (models.Model)

id: <IntegerField> (PK)
created: <DateTimeField>
updated: <DateTimeField>
created_by: User (FK)
display_name: <CharField>
participants: User (FK)
project: Project (FK)

HackProject (models.Model)

id: <IntegerField> (PK)
created: <DateTimeField>
updated: <DateTimeField>
created_by: User (FK)
display_name: <CharField>
description: <TextField>
githubLink: <CharField>
collabLink: <CharField>
submissionTime: <DateTimeField>
scores: HackProjectScore (FK)
mentor: User (FK)

HackProjectScore (models.Model)

id: <IntegerField> (PK)
created: <DateTimeField>
updated: <DateTimeField>
created_by: User (FK)
judge: User (FK)
score: HackProjectScoreCategory (FK)

HackProjectScoreCategory (models.Model)

id: <IntegerField> (PK)
created: <DateTimeField>
updated: <DateTimeField>
created_by: User (FK)
category: <CharField>
score: <IntegerField>

HackAwardCategory (models.Model)

id: <IntegerField> (PK)
created: <DateTimeField>
updated: <DateTimeField>
created_by: User (FK)
display_name: <CharField>
description: <TextField>
winningProject: HackProject (FK)

Commiting your changes

  • Once you're happy with all changes, you can commit and push your code to the appropriate branch:
    • git add <files>
    • git commit -m "#ID: Your commit message details"
    • git push origin <BRANCH_NAME>
    • reminder: do not attempt to push to the master branch!

Creating a Pull Request (PR)

  • Finally, you will need to open a Pull Request on GitHub, detailing all required information:
    • From your forked repo, the PR should look something like this:
      • base repository: Code-Institute-Community/ci-hackathon-app
      • base: master
      • head repository: your-own-account/forked repo
      • compare: your-own-branch
  • If you've added code that should be tested, please attempt to add the required tests.
  • Make sure you address any known issues/bugs/warnings/errors.
  • If you make visual changes, please include tested screenshots.
  • If you make any existing code better, please let us know in your PR description.
  • If contributing to specific User Stories, please be sure to include the appropriate User Story ID.
    • #M01 (Miscellaneous User Story #01)
    • #P02 (Participant User Story #02)
    • #S03 (Staff User Story #03)
    • #A04 (Admin User Story #04)

Please use this guide when creating your PRs

  • User Story ID:
    • list the user story #ID for easier tracking (eg: #P01, #S02, #M03, #A04)
  • Description of PR:
    • description about what you're requesting in the PR
    • try to be thorough, but concise
  • Tests:
    • list any testing you've done; manual or automated
    • this could be code validation, unit tests, browser compatibility, responsiveness testing, etc.
  • Know bugs/errors:
    • list any known bugs/errors, or outstanding items that are still present
  • Screenshots:
    • you can paste screenshots directly into the PR if needed

Happy Coding, and thanks for Contributing to the Code Institute Community!

Additional Resources

Working with a forked repo

Clone this wiki locally