As a developer, I want to easily reference (and update as needed) development practices for our project, so I can follow best development practices and our project maintains consistent code quality.
On 9/30's engineering huddle, we decided to consolidate team practices into a dev-practices folder. Currently this folder includes code-review.md which includes PR best practices that we moved from our PR template in https://github.com/cisagov/manage.get.gov/issues/2140. Since code-review.md also includes coding best practices from our PR template, our 2 viable options are:
Turn code-review.md into a general dev standards page (example: CCAO data handbook.md) which has a PR review section and coding standards section.
Split code-review.md into code-review.md with PR practices and code-standards.md
Acceptance Criteria
[ ] Choose one of the above options to organize our code review and coding practices in our dev-practices folder.
[ ] Update dev-practices folder to add docs for relevant engineering practices on .gov project. Think of what engineering practices would be useful to someone first onboarding onto .gov. Possible examples include (but may not necessarily): PR reviews, naming conventions, testing conventions, our conventions for overriding USWDS, [comment conventions](Consider adapting contents of conventional comments guide).
[ ] Remove outdated information in engineering standards docs (mainly thinking of Contributing.md and our scripts docs).
[ ] Present updated dev-practices docs at engineering huddle for team review.
Additional Context
Engineering Huddle Notes
Engineering standards library - Our engineering practices are spread out across separate docs (PR review template, accessibility, contributing.md in our repo) that we can just put in one place. We can collect our engineering standards into one library/handbook, especially so people who onboard can more easily reference how to do things.
The idea is to have a living doc of engineering practices that cannot (easily) be inferred by simply looking at our codebase.
Possible References
Our engineering standards library does not necessarily have to be as complex as these examples if that's what fits our needs.
Story
As a developer, I want to easily reference (and update as needed) development practices for our project, so I can follow best development practices and our project maintains consistent code quality.
On 9/30's engineering huddle, we decided to consolidate team practices into a dev-practices folder. Currently this folder includes code-review.md which includes PR best practices that we moved from our PR template in https://github.com/cisagov/manage.get.gov/issues/2140. Since code-review.md also includes coding best practices from our PR template, our 2 viable options are:
Acceptance Criteria
Additional Context
Engineering Huddle Notes
Engineering standards library - Our engineering practices are spread out across separate docs (PR review template, accessibility, contributing.md in our repo) that we can just put in one place. We can collect our engineering standards into one library/handbook, especially so people who onboard can more easily reference how to do things.
The idea is to have a living doc of engineering practices that cannot (easily) be inferred by simply looking at our codebase.
Possible References Our engineering standards library does not necessarily have to be as complex as these examples if that's what fits our needs.
Issue Links
No response