The following guide is for members of the project team who have access to the repository as well as code contributors. The main difference between internal and external contributions is that externabl contributors will need to fork the project and will not be able to merge their own pull requests. For more information on contribributing, see: CONTRIBUTING.md.
This project is monorepo with several apps. Please see the api and frontend READMEs for information on spinning up those projects locally. Also see the project documentation for more info.
Each application has its own linting and testing guidelines. Lint and code tests are run on each commit, so linters and tests should be run locally before commiting.
This project follows trunk-based development, which means:
- Make small changes in short-lived feature branches and merge to
mainfrequently. - Be open to submitting multiple small pull requests for a single ticket (i.e. reference the same ticket across multiple pull requests).
- Treat each change you merge to
mainas immediately deployable to production. Do not merge changes that depend on subsequent changes you plan to make, even if you plan to make those changes shortly. - Ticket any unfinished or partially finished work.
- Tests should be written for changes introduced, and adhere to the text percentage threshold determined by the project.
This project uses continuous deployment using Github Actions which is configured in the ./github/worfklows directory.
Pull-requests are merged to main and the changes are immediately deployed to the development environment. Releases are created to push changes to production.
Prefix the branch name with your name, and include the ticket number in the branch name e.g. cooldev/issue-1234-new-feature.
Commit messages should, but are not required, to follow git best practice conventions for consistency and legibility. Commit messages will be squashed, so individual commit messages will only be visible in the commit history of the pull request.
Pull request should have the following format: [Issue N] Description. The description should follow the imperative voice and lack of period from the git best practice conventions.
Use draft PRs to solicit early feedback.
If your PR is a work-in-progress, or if you are looking for specific feedback on things, create a Draft Pull Request and state what you are looking for in the description.
Provide context for current and future team members. Write a full description that provides all the necessary context for your change. Consider your description as documentation. Include relevant context and business requirements, and add preemptive comments (in code or PR) for sections of code that may be confusing or worth debate.
Make things easy for your reviewers.
Do a self-review using the diff in github to make sure you’re not sending through any obvious issues. Run any automations (testing, linters, etc.) before opening your PR.
If any manual testing was performed, document it in enough detail in the PR description that somebody else could recreate your test. Include reference to your test data, if applicable!
Assign reviewers applicable to the domain of your pull request. See CODEOWNERS for more details.
Once a PR is accepted by a reviewer, the author should merge.
This project uses the squash merge strategy. When squashing, retain the [Issue N] Description format. Any notes in the body of the commit should follow commit best practices.
All changes, including small ones, should have an issue. If they don't [Hotfix] should be used in lieu of the issue and number.
This project takes a very collaborative and agile approach to code reviews. Working versions of code, self-organizing, and individuals are prioritized When reviewing pull requests:
- Be prompt. Aim to respond to a review within 24 hours (although sooner is preferable), and if you cannot do so, be sure to communicate delays to the code author.
- Be kind and respectful when leaving comments and maintain a collaborative tone. Don’t use language that disparages or embarrasses the author (name calling, insults to intelligence, etc). Direct any negative feedback towards the code rather than towards the author.
- Present suggestions as requests rather than demands; instead of “Move this function to file B” try “Would this function fit better in file B?” This allows the author to push back on the suggestion by answering a question rather than rejecting a demand, which helps keep things from getting combative.
- Praise and compliment the good parts!
- Explain suggestions and recommendations. These should be opportunities for learning/mentoring, not for criticism or giving orders.
- Offer to chat in person for more complex discussions, or to ensure understanding of new logic.
- Review the testing as well as the code. You may think of edge cases or other things that the author’s testing plan might have missed.
- Clearly designate between required and optional changes. This can take many forms, but as examples: “(optional) We might want to rename this variable to avoid confusion” and “(blocking) We don’t properly handle deadlocks here, so we’ll need to fix that.” It may also be helpful to clearly designate praises, questions, nits, etc to make a comment’s intention very clear.
- Consider using conventional comments for messages.
- Use the "Add a suggestion" feature to suggest small changes in PRs.
- The "Request Changes" feature requires the reviewer approve changes. This takes autonomy from the engineer, and should only be used if there is an urgent need.
Releases follow the CalVer versioning using a YYYY.MM.DD-N format.
Releases are created in Github and with a log of changes.
Step by step instructions for creating a release:
- In your terminal,
git switch mainandgit pullto sync your local code with the latest main commit - In your terminal,
git tag YYYY.MM.DD-N(FILLED IN!) andgit push --tagsto tag and push your CalVer tag- Start with
N=1for a release, incrementing if there is another release on the same day. So the first release on2000.10.10would be2000.10.10-1, ths second release on that day would be2000.10.10-2, etc.
- Start with
- On Github.com, open the Releases page: https://github.com/HHS/simpler-grants-gov/releases
- Click "Draft a new release"
- Choose the tag you just pushed as the current tag, and the last CalVer release as the previous tag
- Click "Generate release notes" to auto-generate release notes
- Click "Publish" to finalize this step
- On Github.com, open the Actions page: https://github.com/HHS/simpler-grants-gov/actions
- You should see Actions that correspond to your release. Follow their status to ensure that they succeed. Follow-up may be required if the Github Actions fail. Here's some places where you might see Github Actions status:
Any changes to features, tools, or workflows should include updates or additions to documentation.
Artillery.io is the open source tool used to load test the application. You can find the yml file for the frontend load test at /frontend/artillery-load-test.yml. You can find the yml file for the backend API load test at /api/artillery-load-test.yml.
To run the load test:
- Install artillery locally if you haven't done so with
npm install -g artillery@latest - For the frontend, download the required data from https://drive.google.com/file/d/1zknvVSRqL7xs8VGinztuKelfppYlgRoP and save "params.json" to
frontend/tests/artillery/params.json $ cd apior or$ cd frontend$ make load-test-<env>where env is eitherlocal,dev,staging, orproduction
make load-test-local- requires running a local container in another console
make load-test-devmake load-test-stagingmake load-test-prod