Starter Code V2

Starter Code for Blueprint projects, brought to you by the UW Blueprint Internal Tools team! 🏗️

Starter Code is an easy to set up, flexible, and customizable bootstrap that aims to encourage best development practices and provide baseline implementations of features common to UW Blueprint projects. 24 different stack combinations are supported, allowing "mix and match" between our most commonly used technologies. For more information on the motivation and design decisions behind Starter Code, please check out the home page of our documentation site!

Teams should adopt Starter Code and use it as a foundation to get their projects off the ground faster, and as a guideline for how to structure their applications. We hope Starter Code will help project teams output higher quality and maintainable code, and allow them to focus on building cool, interesting features instead of setting up and doing boilerplate work. Put simply, Starter Code is here to help us deliver more value to our NPO partners.

Stack Choices

Backend Language: TypeScript (Express.js on Node.js) or Python (with Flask)
Backend API: REST or GraphQL
Database: PostgreSQL or MongoDB
User Auth: Opt-in or opt-out
File Storage: Opt-in or opt-out

The provided frontend is a React application written in TypeScript.

Key Features & Benefits

• Many stack combinations, built with separation of concerns in mind to make it easy to swap out layers of the codebase as needed
• Prebuilt authentication and authorization services, including Google OAuth integration
• Basic CRUD services via PostgresSQL and MongoDB ORMs
• Email service
• File storage service
• CSV export utilities
• Out of the box support for deployment to Firebase Hosting (frontend) and Heroku (backend) via CI/CD pipelines
• Lots of examples of programming best practices in both the frontend and backend

Table of Contents

• 📝 Documentation
• ❗❗ Reporting Issues
• 👨‍💻 Getting Started: Users
• 👷 Getting Started: Internal Tools Developers
  • ✔️ Prerequisites
  • ⚙️ Set up
• 🚀 Creating a Release
• 🧰 Useful Commands
  • ℹ️ Get Names & Statuses of Running Containers
  • 💽 Accessing PostgreSQL Database
  • ✨ Linting & Formatting
  • 🧪 Running Tests
• ✍️ Updating Documentation
• 🌳 Version Control Guide
  • 🌿 Branching
  • 🔒 Commits

Documentation

https://uwblueprint.github.io/starter-code-v2

Reporting Issues

You can open an issue in this GitHub repository, or message the #internal-tools-help channel in UW Blueprint’s Slack workspace.

Getting Started: Users

Please follow the instructions in this guide to generate and set up Starter Code. Starter Code must be preprocessed through the create-bp-app CLI tool before being used, so please do not clone and run this repository directly.

---

Getting Started: Internal Tools Developers

Prerequisites

• Install Docker Desktop (MacOS | Windows (Home) | Windows (Pro, Enterprise, Education) | Linux) and ensure that it is running

# these commands should give error-free output
docker info
docker-compose --version

• Ask a member of the Internal Tools team to be added to our Firebase and MongoDB Atlas projects
• Set up Vault client for secret management, see instructions here

Set up

1. Clone this repository and cd into the project folder

git clone https://github.com/uwblueprint/starter-code-v2.git
cd starter-code-v2

2. Comment out one of the backend services in docker-compose.yml
3. Follow through our public docs
4. In the root .env file, change the name of the MongoDB database according to the backend you're using: either typescript-test or python-test
5. Run the application

docker-compose up --build

The backend runs at http://localhost:8080 and the frontend runs at http://localhost:3000. By default, we use GraphQL (with TypeScript backend), REST (with Python backend), MongoDB, with user auth.

Creating a Release

To update the release branch with commits from main:

1. Create a new branch off the release branch
2. Merge main into the new branch
3. Open a PR from your new branch -> release branch
4. Reviewers should be able to see just the changes from the new main commits
5. Merge the PR, it should just show up as a single commit in the commit history of the release branch
6. Tag the most recent main commit included in the release

git tag <semver> <short-hash-of-main-commit>
git push origin --tags

Useful Commands

Get Names & Statuses of Running Containers

docker ps

Accessing PostgreSQL Database

# run a bash shell in the container
docker exec -it scv2_db /bin/bash

# in container now
psql -U postgres -d scv2

# in postgres shell, some common commands:
# display all table names
\dt
# quit
\q
# you can run any SQL query, don't forget the semicolon!
SELECT * FROM <table-name>;

Linting & Formatting

Python backend:

docker exec -it scv2_py_backend /bin/bash -c "black ."

TypeScript backend and frontend:

# linting & formatting warnings only
docker exec -it scv2_ts_backend /bin/bash -c "yarn lint"

# linting with fix & formatting
docker exec -it scv2_ts_backend /bin/bash -c "yarn fix"

Running Tests

Python backend:

docker exec -it scv2_py_backend /bin/bash -c "pip install -e . && pytest"

TypeScript backend and frontend:

docker exec -it scv2_ts_backend /bin/bash -c "yarn test"

Updating Documentation

To update documentation, checkout the gh-pages branch:

git checkout gh-pages

All documentation should be added to the docs folder. After making changes, commit and push to GitHub. The changes will be automatically deployed.

We use Jekyll to build the site, so you will need to install some additional dependencies to run the site locally. See this article for more details.

To run locally:

bundle exec jekyll serve

Version Control Guide

Branching

• Branch off of main for all feature work and bug fixes, creating a "feature branch". Prefix the feature branch name with your name. The branch name should be in kebab case and it should be short and descriptive. E.g. sherry/readme-update
• To integrate changes on main into your feature branch, use rebase instead of merge

# currently working on feature branch, there are new commits on main
git pull origin main --rebase

# if there are conflicts, resolve them and then:
git add .
git rebase --continue

# force push to remote feature branch
git push -f

Commits

• Commits should be atomic (guideline: the commit is self-contained; a reviewer could make sense of it even if they viewed the commit diff in isolation)
• Trivial commits (e.g. fixing a typo in the previous commit, formatting changes) should be squashed or fixup'd into the last non-trivial commit

# last commit contained a typo, fixed now
git add .
git commit -m "Fix typo"

# fixup into previous commit through interactive rebase
# x in HEAD~x refers to the last x commits you want to view
git rebase -i HEAD~2
# text editor opens, follow instructions in there to fixup

# force push to remote feature branch
git push -f

• Commit messages and PR names are descriptive and written in imperative tense¹. The first word should be capitalized. E.g. "Create user REST endpoints", not "Created user REST endpoints"
• PRs can contain multiple commits, they do not need to be squashed together before merging as long as each commit is atomic. Our repo is configured to only allow squash commits to main so the entire PR will appear as 1 commit on main, but the individual commits are preserved when viewing the PR.

---

1: From Git's own guidelines