This page contains instructions for setting up the local development environment, resolving port conflicts, and our team's standard operating procedures (SOPs) for branching, code review, and automatic AWS deployment.

• Python 3.12 (python --version or python3.12 --version)
• Git (git --version)
• A personal fork of gcivil-nyu-org/team3-mon-fall26 under your GitHub account (remember to uncheck "Copy the main branch only" when creating your fork).

We follow the standard Fork-and-Pull convention:

• origin points to your personal fork (where you push your feature branches).
• upstream points to the main team repository (gcivil-nyu-org/team3-mon-fall26, where everyone pulls develop from and opens PRs into).

git clone https://github.com/<YOUR-GITHUB-USERNAME>/team3-mon-fall26.git
cd team3-mon-fall26
git remote add upstream https://github.com/gcivil-nyu-org/team3-mon-fall26.git
git fetch upstream
git checkout develop

If your local origin currently points to gcivil-nyu-org/team3-mon-fall26, run these two commands inside your project folder:

git remote rename origin upstream
git remote add origin https://github.com/<YOUR-GITHUB-USERNAME>/team3-mon-fall26.git

Verify your remotes with git remote -v:

origin    https://github.com/<YOUR-GITHUB-USERNAME>/team3-mon-fall26.git (fetch)
origin    https://github.com/<YOUR-GITHUB-USERNAME>/team3-mon-fall26.git (push)
upstream  https://github.com/gcivil-nyu-org/team3-mon-fall26.git (fetch)
upstream  https://github.com/gcivil-nyu-org/team3-mon-fall26.git (push)

Always use an isolated virtual environment (.venv) so packages do not conflict with your system Python.

macOS / Linux:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Windows (PowerShell):

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

(Note for Windows: If PowerShell blocks script execution, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once.)

Local development uses config/settings.py by default, which stores data in a local SQLite file (db.sqlite3).

1. Apply database migrations:

   python manage.py migrate

2. (Optional) Create a local admin superuser:

   python manage.py createsuperuser

3. Start the local development server:

   python manage.py runserver

4. Open http://127.0.0.1:8000/ in your browser.
   • / — Landing page
   • /login/ & /register/ — Authentication flows
   • /health/ — Liveness probe ({"status": "ok"})
   • /ready/ — Database readiness probe ({"status": "ok"})

If port 8000 is occupied by a previous terminal session or another service:

• Quickest fix (run on an alternate port):

  python manage.py runserver 8001

• Stop the process occupying port 8000:
  • macOS / Linux:

    lsof -ti:8000 | xargs kill -9

  • Windows (PowerShell):

    Get-NetTCPConnection -LocalPort 8000 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Before pushing any branch, run the same checks that GitHub Actions runs in CI:

# 1. Verify package dependencies and Django system checks
python -m pip check
python manage.py check

# 2. Ensure no model changes are missing migrations
python manage.py makemigrations --check --dry-run

# 3. Run Django application tests
python manage.py test

# 4. Run infrastructure & deployment safeguard unit tests
python -m unittest discover -s infra -p "test_*.py"

• No local AWS keys are needed for normal development: Automatic deployments from develop to AWS Elastic Beanstalk authenticate using keyless GitHub OIDC (nyc-active-github-deploy IAM role).
• Never commit secrets or local state: .env*, db.sqlite3, .venv/, .pem, and .key files are strictly excluded via .gitignore and blocked by our CI bundler check (infra/deploy_ci.py).
• Production vs. Local Settings:
  • Local: Uses config.settings with db.sqlite3.
  • AWS Production (https://dgaeptdmd25z5.cloudfront.net/): Uses config.production with PostgreSQL 16 (127.0.0.1:5432 over TLS) and hourly encrypted S3 backups. See docs/deployment.md and docs/cost-controls.md for full details.

Always branch off the latest upstream/develop and use a descriptive name:

• feature/<short-description> (e.g., feature/event-creation-form)
• fix/<short-description> (e.g., fix/login-redirect)
• docs/<short-description> (e.g., docs/epic3-sequence-diagrams)
• <name>-<feature> (e.g., derah-login, ivan-parks-ingestion)

git checkout develop
git pull upstream develop

(Optional: run git push origin develop to keep your fork's develop branch on GitHub synced as well.)

git checkout -b feature/your-task-name

Keep commits focused and write clear, imperative commit messages:

python manage.py test
git status
git add <files>
git commit -m "Add event creation view and form validation"

(Double-check git status before committing to ensure you never stage db.sqlite3, .env, or temporary scratch files.)

git push -u origin feature/your-task-name

1. Go to https://github.com/gcivil-nyu-org/team3-mon-fall26/pulls and click New pull request (or click the Compare & pull request banner on your fork).
2. Verify the branch selectors at the top:
   • base repository: gcivil-nyu-org/team3-mon-fall26 | base: develop (⚠️ Make sure this is develop, NOT main!)
   • head repository: <YOUR-GITHUB-USERNAME>/team3-mon-fall26 | compare: feature/your-task-name
3. Link the relevant ZenHub / GitHub Issue in your PR description and summarize what changed and how to test it.

1. Automated CI Gate (Test and deploy develop):
   • Every PR targeting develop triggers .github/workflows/deploy-develop.yml.
   • All checks (pip check, manage.py check, makemigrations --check, manage.py test, infra unit tests, and hook syntax checks) must be green before merging.
2. Database Migration Safety:
   • Because AWS auto-rollback restores the previous code version without reversing schema migrations, ensure any new database migrations are backwards-compatible.
3. Peer Review:
   • At least 1 teammate should review and approve the PR before merging into develop.
4. Automatic AWS Deployment After Merge:
   • Once merged into develop, the deploy job in GitHub Actions automatically packages the commit, checks the team's $15 monthly AWS budget guard, deploys to Elastic Beanstalk, runs migrate + collectstatic (with automatic pre/post-migration S3 PostgreSQL backups), and verifies that /, /health/, and /ready/ return HTTP 200 over HTTPS at https://dgaeptdmd25z5.cloudfront.net/.
5. Post-Merge Cleanup: After your PR is merged, clean up your local feature branch:

   git checkout develop
   git pull upstream develop
   git branch -d feature/your-task-name