Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
133 lines (102 loc) · 4.53 KB

CONTRIBUTING.md

File metadata and controls

133 lines (102 loc) · 4.53 KB

Contributors Guide

Thanks for your interest in contributing to the project!

Frameworks and Tools

Name Context Links
Django Web framework Get Started, Documentation
Celery Async task execution, monitoring, scheduling Introduction, Documentation
MariaDB Django/Celery database backend About, Documentation
RabbitMQ Celery broker Get Started, Documentation
Redis Caching, session store, task result backend Get Started
Bootstrap UI design Documentation
Pipenv Env virtualization, reqirements management Documentation

Repository Overview

Programming-Contest-Suite/
├── deploy/
├── docs/
├── scripts/
├── src/
├── utils/
├── .dockerignore
├── .gitignore
├── Dockerfile
├── Pipfile
├── Pipfile.lock
├── requirements-dev.txt
└── requirements.txt
  • deploy: example deployment files useful for development and testing
  • docs: project documentation
  • scripts: shell scripts for executing various project services
  • src: project source code
  • utils: helper tools for input file creation
  • .dockerignore: specifies files and directories ignored by docker build
  • .gitignore: specifies files and directories ignored by git
  • Dockerfile: specifies the construction of the project's Docker image
  • Pipfile: high level project requirements file used by Pipenv
  • Pipfile.lock: the full project requirements built from the Pipfile
  • requirements-dev.txt: project requirments for development and debug
  • requirements.txt: project requirements for production

Source Overview

Programming-Contest-Suite/
└── src/
    ├── announcements/
    ├── assets/
    ├── checkin/
    ├── contestadmin/
    ├── contestsuite/
    ├── core/
    ├── lfg/
    ├── manager/
    ├── media/
    ├── register/
    ├── static/
    ├── templates/
    └── manage.py
  • announcements: display and distribute contest announcements
  • assets: static files utilized project-wide
  • checkin: contest day check-in
  • contestadmin: contest administration interface
  • contestsuite: settings directory for Django and Celery
  • core: site's public facing pages
  • lfg: Looking For Group service
  • manager: user profile and team management
  • media: target directory for files generated by or uploaded to the PCS (placeholder dir)
  • register: user account registration and team creation
  • static: target directory for all project static files upon deployment (placeholder dir)
  • templates: target directory for all project HTML templates upon deployment
  • manage.py: Django management entrypoint

Testing & Development Server

deploy/docker-compose.yml contains an example deployment intended for Docker Compose and suitable for local testing and development.

If you are running the development deployment for the first time, or have made any changes to the project's Celery tasks, run:

docker compose build

Launch the project:

docker compose up

NOTE: In order to monitor the debug logs, as well as view any emails the system sends while in debug, it is suggested to NOT use the -d flag with the docker compose up command.

Project Requirements

Initialize Virtual Environment

# Programming-Contest-Suite/

pipenv install

Update requirements.txt

Production

# Programming-Contest-Suite/

pipenv requirements > requirements.txt

Development

# Programming-Contest-Suite/

pipenv requirements --dev > requirements-dev.txt

Documentation

All project documentation is located in docs/. We utilize the Just the Docs Jekyll theme to style our documentation in Github Pages.

Versioning

We use something similar to SemVer:

  • MAJOR version for significant codebase rewrites.
  • MINOR version for localized changes, e.g. adding a new feature.
  • PATCH version for any adjustment to main codebase, e.g. bugfix.