Skip to main content

DevOps

Last updated:
5/8/2023

DevOps is the combination of cultural philosophies, practices, and tools that enable teams to rapidly and continuously deliver high-quality software through the adoption of Agile and Lean methodologies, workflow automation, and fast feedback loops.

Workflow

  • Break down work into the smallest incremental change possible
  • Limit work in progress to 2-3 items per person
  • Pull the latest code every day and before starting new development
  • Continually test changes throughout the development cycle
  • Create frequent, small pull requests that touch as few files as possible
  • Submit pull requests for code review
  • Address code review feedback
  • Perform peer code reviews on the latest pull requests

Development practices

Anyone should be able to understand the full history of a repository by quickly scanning the list of pull requests and commits within it.

Follow the practices below to increase quality, efficiency, and transparency.

Branches

  • Follow the feature branch workflow
  • Pull the latest code before creating a new branch
  • Name branches concisely and descriptively
  • Prefix branch names with "feature" or "bug"
    • I.e., feature/feature-name or bug/bug-name
    • E.g.: bug/readme-typos
  • Avoid sharing branches

Testing

  • Continually test changes throughout the web development cycle
    • Testing is not a single step that happens after 'dev complete'
    • Testing should happen through the entire web development cycle, e.g.: usability testing, dev testing, accessibility testing, cross-browser testing, unit and end-to-end testing, QA testing, performance testing, automated testing, manual testing, etc.
    • We recommend Cypress for end-to-end tests, and Jest and Testing Library for unit tests

Commits

  • Before committing, run linters to enforce best practices and coding standards, reduce the amount of human code review needed, and allow code reviewers to focus on providing higher-level feedback
  • Commit early and often
    • A commit should include a complete, isolated change
    • Follow the single responsibility principle whenever possible
    • Think about what other work would be lost if we had to roll back
  • Write concise and descriptive commit messages
    • Limit the length to ~50-75 characters
    • Use the imperative mood
      • The imperative mood forms a command or request
      • This is an established convention for system-generated commits in Git, e.g.: Merge branch 'bug/readme-typos'
    • A properly formed commit message should complete the following sentence: "If applied, this commit will [commit message]"
      • For example, "If applied, this commit will fix typos in the README" translates to "Fix typos in the README"
    • A series of commits should act as a step-by-step summary of the code changes within a pull request

Pull requests

  • Before creating a pull request, review your own code
    • Resolve conflicts — do not rely on auto-merge features
    • Carefully compare diffs line by line against the latest version
    • Ensure any unintended changes are not included
    • Clean up any typos, trailing white space, commented out code, debuggers, and TODOs
  • Create frequent pull requests
    • A pull request should only contain changes corresponding to a single ticket
    • Keep pull requests small and focused
    • Modify as few files as possible
    • Think about what other work would be lost if we had to roll back
    • Create draft pull requests when opening pull requests that contain changes that are not ready to be reviewed or merged
  • Name pull requests concisely and descriptively
    • Whenever possible, include a JIRA ticket number and enforce this practice through tooling
    • Avoid generic names like "bug fix"
    • Use descriptive names to help keep pull requests small and focused
  • Use the pull request description to provide additional context to the changes
    • At a minimum, describe what changes are being introduced and why
    • Consider including before and after screenshots of visual changes in the pull request description
    • Do not use the pull request description as a substitute for self-explanatory or "self-commenting" code supplemented by code comments

Code review

When reviewing code:

  • Do not begin the code review process on a draft pull request or a pull request that has merge conflicts, fails to compile, or fails automated checks
  • Begin the review process as soon as possible
  • Ask another reviewer to provide additional feedback, especially if you are unfamiliar with the code or concepts — two reviewers are better than one

When providing feedback:

  • Explain what should be changed and why it should be changed
  • Focus on function first, cleanliness and maintainability second, and optimization last — all three matter, but so does the order in which they're resolved

When remediating feedback:

  • Remediate code review feedback within the same pull request to avoid splitting the history
    • If remediating something identified during code review would cause the pull request to become too large, create a follow-up JIRA ticket and reply to the code review comment with a link to the ticket
  • Do not introduce new, unrelated changes after the code review process has started

Documentation

  • Write, or update, documentation about all new changes
  • Document all code review conversations in comment threads — avoid having one-off conversations to prevent the loss of context or information

Merging

  • Do not merge a pull request unless the code it contains is production-ready
  • Do not merge a pull request that has not been approved, fails to compile, or fails automated checks
  • Delete the feature branch after merging the pull request