If you haven't already, please visit the Getting Started for Local Development.
The repository uses GitHub Flow, a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly. GitHub Flow aligns with continuous delivery of modern web applications where changes are not rolled back and multiple versions of software don't need to be supported.
How to Use GitHub Flow
- Fork the repo and create a support branch
- Forking ensures the upstream repository can only be affected through a pull request (PR)
masterbranch is not affected by branching
- Add commits
- Make sure
pre-commitchecks pass before each commit because CI/CD enforces them
- Make sure
- Open a PR
- Encourages questions or comments from reviewers
- Check to see if your branch passes the CI/CD build
- Discuss and review your code
- You can continue to push to your branch as discussion happens, such as to address bugs
- Once your PR has been reviewed and the branch passes the CI/CD build, you can deploy to verify them in production
- For our case, we use a specifically provisioned testing environment that resembles production
- Squash and rebase
- After verification in the test environment, squash your commits into a single buildable commit
- Rebase your branch on top of master and handle conflicts
- Merge PR
- Merge the PR into
masterand delete the branch
- Merge the PR into
mastermust always be deployable
- Never push directly to
- Always test your deployments on a test server
Things to Avoid
- Don't merge in broken or commented out code
- Don't commit onto
- Don't merge with conflicts -- handle conflicts upon rebasing
The repository uses the
pre-commit package to manage pre-commit hooks for the quality assurance tools.
These hooks help enforce software standards and identify simple issues at the commit level before submitting code reviews.
Install into your cloned repo
# Activate virtual environment source activate backend/venv/bin/activate # Install into your repo's .git directory pre-commit install
Automatically run all pre-commit hooks (just commit)
git commit -m '...'
Manually run all pre-commit hooks
pre-commit run --all-files.
Run individual hook
# Available hook ids: trailing-whitespace, end-of-file-fixer, check-yaml, black, isort, flake8, mypy pre-commit run <hook_id>.
Types of Support Branches
feature/branches used to develop new features
- The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into master.
hotfix/branches arise from the necessity to act immediately upon an undesired state of a live production version
- When a critical bug in a production version must be resolved immediately, a hotfix branch may be branched off from the master branch.
docs/branches are used when there are only documentation related updates without new features
Branch Naming Convention
Make sure to reference the issue number related to the branch, along with a clear description (use your issue title for reference).
Squash and Rebase Commits
Before you merge a support branch back into
master, your support branch should be squashed down to a single buildable commit, and then rebased from the up-to-date
Why squash and rebase commits?
- Ensures build passes from the commit
- Cleans up Git history for easy navigation
- Makes collaboration process more efficient
- Makes handling conflicts from rebasing simple since you only have to deal with conflicted commits
git bisecteasier and more effective to use. For example, it will show the exact commit that introduced a bug since the commit contains a relatively small changeset. On the otherhand, merge commits make it much harder since it includes a large changeset.
How to squash and rebase commits
git checkout master git rebase upstream/master git push -f origin master
Rebase branch onto
git checkout branchName git rebase master git push -f origin branchName
Get the SHA of the commit OR number of commits to rebase to
git log --graph --decorate --pretty=oneline --abbrev-commit
git rebase -i [SHA] OR git rebase -i HEAD~[NUMBER OF COMMITS]
Resolve merge conflicts if they exist
- Make sure your squashed commit messages are refined
- Force push to remote branch
git push -f origin branchName
Quality Assurance Tools
|Platform||Code Formatter||Linter||Type Checker|
|Front-end||prettier||ESLint + Airbnb||TypeScript (language)|
Ways to Run Tools
pre-commit- recommend in most cases, commands found here
- Using IDE/text editor - recommended alongside #1 for integrated linting and formatting, only VSCode
settings.jsonfile provided for configuration
- Using terminal to run standalone tool - useful to test configs. Visit the tool's site for a list of commands
In most cases, code should be self-documenting.
If necessary, documentation should explain why something is done, its purpose, and its goal. The code shows how it is done, so commenting on this can be redundant.
- Embrace documentation as an integral part of the overall development process
- Treat documenting as code and follow principles such as Don't Repeat Yourself and Easier to Change
- Use comments and docstrings to explain ambigiuity, complexity, or to avoid confusion
- Co-locate API documentation with related code
- Use Python type annotations and type comments where helpful
- Be as specific as possible with TypeScript annotations
Things to Avoid
- Don't write comments as a crutch for poor code
- Don't comment every function, data structure, type declaration
Testing and Continuous Integration (CI)
This project uses GitHub Actions to run the CI/CD build. The build is triggered by Git
push (merging PRs) events to the upstream
- Pre-commit Checks - runs formatters and linters
- Back-end CI - runs a
pytesttest suite and uploads coverage report
- Front-end CI - runs a
react-testing-librarytest suite and uploads a coverage report
How do I Know What to Test?
Use code coverage tools to generate a report and see what you should test. Be aware, code coverage tools measure lines of code covered by tests. You should still write test cases that exceed the base testcases.
The repository's code coverage tools have minimum threshold percentages for code coverage. If your PR's CI build causes the code coverage percentage to drop below the limit, your build cannot be merged.