Skip to content

Repository Management

Jump to bottom
Sara Cope edited this page Oct 24, 2020 · 14 revisions

digital.gov Repository Management

This is a living document explaining how we collaboratively manage the digital.gov platform repositories. If you’d like to suggest a change, please open an issue for discussion or submit a pull request to the document.

This document covers:

Issues

We use GitHub issues to track user issues and team tasks. Whenever possible, we follow this outline:

  1. Goal: a quick blurb explaining the bug or what the issue should accomplish. Optional: What is the user need?
  2. Completion criteria: how we’ll know that this issue has been completed
  3. Tasks to completion:
    • Use
    • Markdown
    • Checklists
  4. Dependencies (optional): What other issues out there need to be completed before you can do this one? Include links to tickets with the dependency.
  5. For development issues, include unknown tasks or dependencies that need investigation.

In addition, everyone is encouraged to open issues for figuring out functional testing or exploring new ideas that require some additional research.

A healthy issue list is one where issues are relevant and actionable. Relevant in the sense that they relate to the project’s current priorities. Actionable in the sense that it’s clear what action(s) need to be taken to resolve the issue.

Labels

All issues should have one or more labels which are lower-case with sentence spacing (no hyphens).

Any issues that are irrelevant or not actionable should be closed because they get in the way of making progress on the project. Imagine the issue list as a desk: the more clutter you have on it, the more difficult it is to use the space to get work done.

We have a GitHub Action which runs once a week to identify stale issues and label them as such. Read more about our [Stale bot(https://github.com/GSA/digitalgov.gov/blob/master/.github/workflows/close-stale-issue.yml).

GitHub allows you to assign labels to Issues and Pull Requests. For digital.gov repos, we use a standard set of labels on all our repos.

We use the label framework needed to tags issues in order for them to show on the code.gov Open Tasks page. These labels are outlined in the code.gov helpwanted.md file.

All Issues and Pull Requests should have at least one label.

Milestones

We put issues into milestones to better categorize them.

Triaging Issues

To keep the issue list healthy, it needs to be triaged regularly. Consider adding this to your sprint planning or closeout routine. Triage is the practice of reviewing existing issues to make sure they’re relevant, actionable, and have all the information they need.

Here are a couple of places you can start:

  • All issues without an assigned label
  • The least recently updated issues (Sort -> Least recently updated)

When reviewing issues, here are some steps you can perform:

  • First search for duplicates. If the issue is duplicate, close it by commenting with “Duplicate of #”, add any relevant new details to the existing issue, and add the [inactive] duplicate label.
  • If the issue is missing labels, add some to better categorize it (requires proper permissions).
  • If the title doesn’t communicate the issue, edit it for clarity (requires proper permissions).
  • If it’s a bug report, test to confirm the report or add the [status] needs testing label. If there is not enough information to confirm the report, add the [status] needs info label and ask for the details needed.
  • Remove the [status] needs info if the author of the issue has responded with enough details.
  • Close the issue with a note if it has a [status] stale label but the author didn't respond in 2+ weeks.
  • If there was a conversation on the issue but no actionable steps identified, follow up with the participants to see what’s actionable.
  • If you feel comfortable triaging the issue further, then you can also:
    • Check that the bug report is valid by debugging it to see if you can track down the technical specifics.
    • Check if the issue is missing some detail and see if you can fill in those details. For instance, if a bug report is missing visual detail, it’s helpful to reproduce the issue locally and upload a screenshot or GIF.

Pull Requests

digital.gov follows a feature branch pull request workflow for all code and documentation changes. At a high-level, the process looks like this:

  1. Check out a new feature branch locally. Use a descriptive branch name specific to the change being made.
  2. Make your changes, testing thoroughly.
  3. Commit your changes when you’re happy with them, and push the branch.
  4. Open your pull request.
  5. Review the preview in Federalist to test the changes are as you expect.

Commit messages

  • Good commit messages start with a verb, like "add" or "change" or "remove."
  • Be sure to talk about the nature of the change you're making. Explain why the change is needed, rather than simply describing the bug or task it addresses.
  • If your commit resolves an issue, reference it in the commit messages. For example "closes #555." Read more GitHub guidance on closing issues via commit messages.

Along with this process, there are a few important points to mention:

  • Create pull requests for all commits, even typo fixes.
  • Non-trivial pull requests should be preceded by a related issue that defines the problem to solve and allows for discussion of the most appropriate solution before actually writing code.
  • To make it far easier to merge your code, each pull request should only contain one conceptual change. Keeping contributions atomic keeps the pull request discussion focused on one topic and makes it possible to approve changes on a case-by-case basis.
  • Separate pull requests can address different items or todos from their linked issue, there’s no need for a single pull request to cover a single issue if the issue is non-trivial.

Review guidelines

  • Complete requested code reviews within 1 business day.
  • If a convo is open-ended or the discussion requires a lot of back-and-forths, then take it to email or Slack for resolution.
  • If the change is one that can be reviewed locally, pull it down to your machine for testing.
  • If the submitter is a core engineering team member, they are responsible for merging their pull request after it has been reviewed/approved by another team member.

Review checklist

  • Does the contribution pass the Submission Guidelines?
  • Do the changes appear as expected in the Federalist preview?
  • Are there any additional related changes that need added? Example, event speakers should also have an author bio.
  • Does the code reduce any of our baseline measures in accessibility, performance, or SEO?
  • Do any tests need added?

GitHub Actions

We have 2 GitHub Actions that run checks on each Pull Request.

Code Review

First, review the TTS Engineering Practice code review guide.

Every pull request goes through a manual code review, in addition to automated tests. The objectives for the code review are best thought of as:

  • Correct — Does the change do what it’s supposed to?
  • Secure — Would a nefarious party find some way to exploit this change?
  • Readable — Will your future self be able to understand this change months down the road?
  • Elegant — Does the change fit aesthetically within the overall style and architecture?
  • Altruistic — How does this change contribute to the greater whole?

As a reviewer, your feedback should be focused on the idea, not the person. Seek to understand, be respectful, and focus on constructive dialog.

As a contributor, your responsibility is to learn from suggestions and iterate your pull request should it be needed based on feedback. Seek to collaborate and produce the best possible contribution to the greater whole.

Design Review

If your pull request impacts the design, you can ask for a designer to review. Most pull requests that have an impact on design are reviewed. However, you can request a design review on something by adding the [status] needs design feedback label. As a guide, this could be:

  • Anything that changes something visually.
  • If you just want design feedback on an idea or exploration.

Continuous Integration

Digital.gov runs a continuous integration script through CircleCI to test each pull request. It includes an automated test for checking the validity of the Hugo generated JSON files used for the API. Currently, it validates authors, images, and topics using the tool jq. If an issue is found with the JSON, jq will return a non-zero exit code causing CircleCI to fail. See the wiki API page for fixing API issues.

Future PRs could improve the messaging behind the failures to provide more context about the problem.

Update a Pull Request to the latest production changes

If a Pull Request has been sitting in the queue a while, or a major update has been released since the Pull Request was started, it's a good idea to update the PR to the latest production release. Follow these steps:

  • On the Pull Request page in GitHub, click on view command line instructions. This opens the dialog to show you how to Merge a Pull Request via the command line. We're not going to perform a merge to production, but the Step 1 instructions here can be used to update the branch. Click the clipboard icon to copy the instructions for Step 1 here. These will look something like:
Screen Shot 2020-07-16 at 9 23 49 AM
  • Open a terminal on your machine and navigate to the digitalgov.gov project folder Example: ➜ digitalgov.gov git:
  • Paste in the text from Step 1. Ex.
git fetch origin
git checkout -b Author-and-Topics-Page-Update origin/Author-and-Topics-Page-Update
git merge main

This will get the latest update from GitHub, checkout the branch for the Pull Request you're updating, and incorporate (commit) the latest changes from production main to your Pull Request branch. This will open a new dialog which allows you to create a commit message for this action. It is not necessary to add or edit a message here. Type :q to exit the commit message dialog.

  • The results will be that the latest commits from main are added to your Pull Request branch. You can confirm this by typing git log to view the git commits on your branch.
  • To send these changes back to GitHub and update your Pull Request, type git push origin head. You can confirm this worked by viewing the latest commit on the Pull Request. Example: https://github.com/GSA/digitalgov.gov/pull/2873/commits

Merging Pull Requests

A pull request can generally be merged once it is:

  • Deemed a worthwhile change to the codebase.
  • In compliance with all relevant code review criteria.
  • Covered by sufficient tests, as necessary.
  • Vetted against all potential edge cases.
  • Changelog entries were properly added.
  • Reviewed by someone other than the original author.

The final pull request merge decision is made by the core team.

Please make sure to assign each merged pull request to its release milestone. Doing so creates the historical legacy of what code landed when, and makes it possible for all project contributors (even non-technical ones) to access this information.

Closing Pull Requests

Sometimes, a pull request may not be mergeable, no matter how much additional effort is applied to it (e.g. out of scope). In these cases, it’s best to communicate with the contributor graciously while describing why the pull request was closed, this encourages productive future involvement.

Make sure to:

  1. Thank the contributor for their time and effort.
  2. Fully explain the reasoning behind the decision to close the pull request.
  3. Link to as much supporting documentation as possible.

If you’d like a template to follow:

Thanks ____ for the time you’ve spent on this pull request.

I’m closing this pull request because ____. To clarify further, ____.

For more details, please see ____ and ____.

Dependency updates

For patch dependency releases follow these steps:

  1. On your local machine, navigate to the root directory of your project using the terminal
  2. To update all dependencies, run npm update
  3. To update a specific package, run npm update <package-name>. For example, npm update uswds; this will generate a new package.json and package-lock.json files
  4. Commit the changes to the package.json and package-lock.json files and enter a Pull Request
  5. Add a note to the pull request linking to the release notes of any relevant package updates

Digital.gov generally uses caret ^ dependency notation, which means running npm update will only bump dependencies that have patch (minor) releases. So in the package.json file, we had uswds 2.6 listed, running npm update would bump it to a minor version like 2.6.2 or 2.6.8. It will not update to the latest minor version release like uswds 2.7 or a major release like uswds 3.0.

For major/minor dependency releases:

  1. On your local machine, navigate to the root directory of your project using the terminal
  2. To update a specific package to a major or minor version run npm install <package@version>. For example, npm install [email protected]

Read more about semantic versioning with major/minor/patch notation Read more about how npm-update works

Releases

For Minor Changes:

Create Release Notes for the project on a monthly basis (at minimum) to document the changes with:

  • the rationale behind the change
  • any research into the reasoning behind the change, if necessary
  • any benefits the user will notice as a result of the change
  • link to the Issue in GitHub (if applicable) for more information, including a simplified way to follow along with the project in GitHub
  • announce a summary of the change in the internal Slack channel of our choice (#digitalgov, #solutions, #general, #innovation, etc), including why TTS’ers should care about this update
  • Submit a summary of the update to the Sol Sentinal internal newsletter

For Major Changes:

Create Release Notes page to document the changes with:

  • the rationale behind the change
  • any research into the reasoning behind the change, if necessary
  • any benefits the user will notice as a result of the change
  • link to the Issue in GitHub (if applicable) for more information, including a simplified way to follow along with the project in GitHub
  • write a blog, linking to the specific Release Notes entry (See #1 above), with any additional context to the problem or interesting information from GitHub
  • add the blog, or link to Release Notes, to our newsletter
  • tweet and add to Facebook, about the blog
  • announce a summary of the change in the internal Slack channel of our choice (#digitalgov, #solutions, #general, #innovation, etc), including why TTS’ers should care about this update
  • submit a summary of update to the GSA Today internal weekly newsletter
  • draft a note to the government-wide Communities of Practice, asking for their input and how they can comment/give feedback

Deprecating a repository

When deprecating a repository, complete the following tasks:

GitHub:

  • Update the README to indicate that the repo has been deprecated
  • Remove any "status" badges from the README file. I.e. build status, maintainability, test coverage, etc.
  • Close all PRs and issues (and comment pointing people to the new repo if applicable)
  • Post and pin a new issue indicating that the repo has been deprecated
  • Update the repo description to indicate that the repo has been deprecated
  • Remove any webhooks on Slack or other platforms
  • Verify that all access is removed except for the maintaining group account. Use digital-gov and digital-gov-engineering (admin access)
  • Add deprecated and archived topic tags to the repo
  • Archive the repo in the GitHub Settings

Other if applicable

🎉Questions? Email [email protected]

Clone this wiki locally