Merge branch 'main' of https://github.com/cisagov/manage.get.gov into…

… hotgov/2852-property-to-portfolio-related-fields

.github/pull_request_template.md

@@ -1,11 +1,7 @@
 ## Ticket
 
+<!-- PR title format: `#issue_number: Descriptive name ideally matching ticket name - [sandbox]`-->
 Resolves #00
-<!--Reminder, when a code change is made that is user facing, beyond content updates, then the following are required:
-- a developer approves the PR
-- a designer approves the PR or checks off all relevant items in this checklist.
-
-All other changes require just a single approving review.-->
 
 ## Changes
 
@@ -45,82 +41,63 @@ All other changes require just a single approving review.-->
 
 - [ ] Met the acceptance criteria, or will meet them in a subsequent PR
 - [ ] Created/modified automated tests
-- [ ] Added at least 2 developers as PR reviewers (only 1 will need to approve)
-- [ ] Messaged on Slack or in standup to notify the team that a PR is ready for review
-- [ ] Changes to “how we do things” are documented in READMEs and or onboarding guide
-- [ ] If any model was updated to modify/add/delete columns, makemigrations was ran and the associated migrations file has been commited.
+- [ ] Update documentation in READMEs and/or onboarding guide
 
 #### Ensured code standards are met (Original Developer)
-
-- [ ] All new functions and methods are commented using plain language
-- [ ] Did dependency updates in Pipfile also get changed in requirements.txt?
+<!-- Mark "- N/A" and check at the end of each check that is not applicable to your PR -->
+- [ ] If any updated dependencies on Pipfile, also update dependencies in requirements.txt.
 - [ ] Interactions with external systems are wrapped in try/except
 - [ ] Error handling exists for unusual or missing values
 
 #### Validated user-facing changes (if applicable)
 
-- [ ] New pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
+- [ ] Tag @dotgov-designers in this PR's Reviewers for design review. If code is not user-facing, delete design reviewer checklist
+- [ ] Verify new pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
 - [ ] Checked keyboard navigability
 - [ ] Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
-- [ ] Add at least 1 designer as PR reviewer
 
 ### As a code reviewer, I have
 
 #### Reviewed, tested, and left feedback about the changes
 
 - [ ] Pulled this branch locally and tested it
-- [ ] Reviewed this code and left comments
+- [ ] Verified code meets all checks above. Address any checks that are not satisfied
+- [ ] Reviewed this code and left comments. Indicate if comments must be addressed before code is merged
 - [ ] Checked that all code is adequately covered by tests
-- [ ] Made it clear which comments need to be addressed before this work is merged
-- [ ] If any model was updated to modify/add/delete columns, makemigrations was ran and the associated migrations file has been commited.
-
-#### Ensured code standards are met (Code reviewer)
-
-- [ ] All new functions and methods are commented using plain language
-- [ ] Interactions with external systems are wrapped in try/except
-- [ ] Error handling exists for unusual or missing values
-- [ ] (Rarely needed) Did dependency updates in Pipfile also get changed in requirements.txt?
+- [ ] Verify migrations are valid and do not conflict with existing migrations
 
 #### Validated user-facing changes as a developer
+**Note:** Multiple code reviewers can share the checklists above, a second reviewer should not make a duplicate checklist. All checks should be checked before approving, even those labeled N/A. 
 
 - [ ] New pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
 - [ ] Checked keyboard navigability
 - [ ] Meets all designs and user flows provided by design/product
 - [ ] Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
-
-- [ ] Tested with multiple browsers, the suggestion is to use ones that the developer didn't (check off which ones were used)
- - [ ] Chrome
- - [ ] Microsoft Edge
- - [ ] FireFox
- - [ ] Safari
-
 - [ ] (Rarely needed) Tested as both an analyst and applicant user
 
-**Note:** Multiple code reviewers can share the checklists above, a second reviewers should not make a duplicate checklist
-
 ### As a designer reviewer, I have
 
 #### Verified that the changes match the design intention
 
 - [ ] Checked that the design translated visually
-- [ ] Checked behavior
+- [ ] Checked behavior. Comment any found issues or broken flows.
 - [ ] Checked different states (empty, one, some, error)
 - [ ] Checked for landmarks, page heading structure, and links
-- [ ] Tried to break the intended flow
 
 #### Validated user-facing changes as a designer
 
 - [ ] Checked keyboard navigability
 - [ ] Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
-
 - [ ] Tested with multiple browsers (check off which ones were used)
  - [ ] Chrome
  - [ ] Microsoft Edge
  - [ ] FireFox
  - [ ] Safari
-
 - [ ] (Rarely needed) Tested as both an analyst and applicant user
 
+### References
+- [Code review best practices](../docs/dev-practices/code_review.md)
+
 ## Screenshots
 
 <!-- If this PR makes visible interface changes, an image of the finished interface can help reviewers

CONTRIBUTING.md

@@ -14,17 +14,6 @@ There are a handful of things we do not commit to the repository:
 For developers, you can auto-deploy your code to your sandbox (if applicable) by naming your branch thusly: jsd/123-feature-description
 Where 'jsd' stands for your initials and sandbox environment name (if you were called John Smith Doe), and 123 matches the ticket number if applicable.
 
-## Approvals
-
-When a code change is made that is not user facing, then the following is required:
-- a developer approves the PR
-
-When a code change is made that is user facing, beyond content updates, then the following are required:
-- a developer approves the PR
-- a designer approves the PR or checks off all relevant items in this checklist
-
-Content or document updates require a single person to approve.
-
 ## Project Management
 
 We use [Github Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) for project management and tracking.
@@ -39,14 +28,6 @@ Every issue in this respository and on the project board should be appropriately
 
 We also have labels for each discipline and for research and project management related tasks. While this repository and project board track development work, we try to document all work related to the project here as well. 
 
-## Pull request etiquette
-
-- The submitter is in charge of merging their PRs unless the approver is given explicit permission.
-- Do not commit to another person's branch unless given explicit permission.
-- Keep pull requests as small as possible. This makes them easier to review and track changes.
-- Bias towards approving i.e. "good to merge once X is fixed" rather than blocking until X is fixed, requiring an additional review.
-- Write descriptive pull requests. This is not only something that makes it easier to review, but is a great source of documentation. 
-
 ## Branch Naming
 
-Our branch naming convention is `name/topic-or-feature`, for example: `lmm/add-contributing-doc`. 
+Our branch naming convention is `name/issue_no-description`, for example: `lmm/1234-add-contributing-doc`. 

docs/dev-practices/code_review.md

@@ -0,0 +1,31 @@
+## Code Review
+
+Pull requests should be titled in the format of `#issue_number: Descriptive name ideally matching ticket name - [sandbox]`
+Pull requests including a migration should be suffixed with ` - MIGRATION`
+
+After creating a pull request, pull request submitters should:
+- Add at least 2 developers as PR reviewers (only 1 will need to approve).
+- Message on Slack or in standup to notify the team that a PR is ready for review.
+- If any model was updated to modify/add/delete columns, run makemigrations and commit the associated migrations file.
+
+## Pull request approvals
+Code changes on user-facing features (excluding content updates) require approval from at least one developer and one designer.
+All other changes require a single approving review.
+
+The submitter is responsible for merging their PR unless the approver is given explicit permission. Similarly, do not commit to another person's branch unless given explicit permission.
+
+Bias towards approving i.e. "good to merge once X is fixed" rather than blocking until X is fixed, requiring an additional review.
+
+## Pull Requests for User-facing changes
+When making or reviewing user-facing changes, test that your changes work on multiple browsers including Chrome, Microsoft Edge, Firefox, and Safari.
+
+Add new pages to the .pa11yci file so they are included in our automated accessibility testing.
+
+## Other Pull request norms
+- Keep pull requests as small as possible. This makes them easier to review and track changes.
+- Write descriptive pull requests. This is not only something that makes it easier to review, but is a great source of documentation. 
+
+## Coding standards
+
+### Plain language
+All functions and methods should use plain language.