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.
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.
- 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
- π Documentation
- ββ Reporting Issues
- π¨βπ» Getting Started: Users
- π· Getting Started: Internal Tools Developers
- βοΈ Prerequisites
- βοΈ Set up
- π Creating a Release
- π§° Useful Commands
- βοΈ Updating Documentation
- π³ Version Control Guide
https://uwblueprint.github.io/starter-code-v2
You can open an issue in this GitHub repository, or message the #internal-tools-help channel in UW Blueprintβs Slack workspace.
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.
- 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
- Clone this repository and
cd
into the project folder
git clone https://github.com/uwblueprint/starter-code-v2.git
cd starter-code-v2
- Comment out one of the backend services in
docker-compose.yml
- Follow through our public docs
- In the root
.env
file, change the name of the MongoDB database according to the backend you're using: eithertypescript-test
orpython-test
- 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.
To update the release branch with commits from main:
- Create a new branch off the release branch
- Merge main into the new branch
- Open a PR from your new branch -> release branch
- Reviewers should be able to see just the changes from the new main commits
- Merge the PR, it should just show up as a single commit in the commit history of the release branch
- Tag the most recent
main
commit included in the release
git tag <semver> <short-hash-of-main-commit>
git push origin --tags
docker ps
# 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>;
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"
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"
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
- 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 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 tense1. 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 onmain
, but the individual commits are preserved when viewing the PR.
1: From Git's own guidelines