2492: Update developer onboarding ticket

[erinysong]

Ticket

Resolves #2492

Changes

• Adds required and recommended software installations on DHS device.
• Adds known issues to setting up developer environment on DHS device.

Context for reviewers

Changes to be discussed in 7/29 engineering huddle. Also interested in opening discussion to explore ways we can organize onboarding to be easier to follow. Considerations include DHS device setup, public/private onboarding info, and the number of docs/links onboarding is spread across.

This PR would ideally deprecate the need for the Developing on a CISA laptop doc.

Setup

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

• 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.

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?
• 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
• 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
• 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?

Validated user-facing changes as a developer

• 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 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

Screenshots

[erinysong]

Would suggest omitting this since this would focus on dev onboarding, unless this was intended to be in the DHS device install suggestions

[zandercymatics]

Couple of suggestions

[zandercymatics]

Maybe we could add some text here in a sub bullet like: - If you'd prefer, install the [Github CLI](https://cli.github.com/) instead?

[erinysong]

Unrelated, but thoughts on moving this to recommended software? I don't think Github CLI/Desktop are necessary for development and more a quality of life option

[zandercymatics]

We do need one or the other, but we could definitely put desktop in there

[zandercymatics]

Suggested change

Some developers, especially those using Government Furnished Equipment (GFE), have problems installing python packages due to an SSL verification failure. This happens because GFE has a custom certificate chain installed, but python uses its own certificate bundle. As a result, when pip tries to verify the TLS connection to download a package, it cannot and so the download fails. To resolve this, if you are running locally you can use --use-feature=truststore to direct pip to use the local certificate store. If you are running a docker container, you will need to export the root certificate and pull it into the container. Ask another developer how to do this properly.

Some developers, especially those using Government Furnished Equipment (GFE), have problems installing python packages due to an SSL verification failure. This happens because GFE has a custom certificate chain installed, but python uses its own certificate bundle. As a result, when pip tries to verify the TLS connection to download a package, it cannot and so the download fails. To resolve this, if you are running locally you can use --use-feature=truststore to direct pip to use the local certificate store. If you are running a docker container, you will need to export the root certificate and pull it into the container.

(nitpick/optional) I think that is implied, right?

[zandercymatics]

Looks great guys. See my two suggestions before merging, but your good to go after those get resolved!

[zandercymatics]

Suggested change

	- [ ] Github Desktop*
	- [ ] Github Desktop* or the Github CLI*

I'd recommend adding this because Github Desktop is a pain to get on linux (its a third party community one). I think either or would work in our case.

[Matt-Spence]

Good point, what we really want is the github cli for running some of our scripts.

[zandercymatics]

Ah yep, sorry I meant github cli

[zandercymatics]

Suggested change

	\* Must be requested through DHS IT portal on DHS devices
	* Must be requested through DHS IT portal on DHS devices

Typo?

[Matt-Spence]

Yep

[zandercymatics]

Looks great!