Skip to content

Latest commit

 

History

History
88 lines (57 loc) · 5.22 KB

README.md

File metadata and controls

88 lines (57 loc) · 5.22 KB

This file is deprecated. The most recent information should be at https://github.com/department-of-veterans-affairs/va.gov-team/tree/master/platform/working-with-vsp/policies-work-norms

Norms for using Github

Background

Teams working on the Veteran-facing Services Platform use Github to

  1. Store and share project documents. We do this to keep a record of project work and so all teams can learn from what other teams are doing.
  2. Store and share Work Practices — our best practices for how we do things.
  3. Use Github Issues to track progress throughout the agile delivery process.
  4. Manage code and related version history.

Tips for creating a Github account

  1. Everyone working on the Veteran-facing Services Platform must set up a Github account.
  2. All content in our VA Github repositories is subject to FOIA.
  3. We strongly recommend that you set up a new Github account for VA work using your VA.gov email address.
  4. We strongly recommend that you do not use a personal Github account for your VA work.
  5. Github requires two-factor authentication (2FA) for new accounts.
    • If you use a Github account without enabling 2FA, you're likely to have problems pushing code.

Using Github

What is Github?

GitHub is a system that stores documents and keeps a revision history of those files. It's divided into "repositories" (or "repos") which are groups of related files or documents. For example, this file lives in the va.gov-vfs-teams repo.

Tips for managing files and folders

  1. Always use a dash (-) between words in file and folder names.
    • If a folder (or a file) name has white space in it, Github fills each white space with %20. E.g., https://github.com/department-of-veterans-affairs/vets.gov-team/tree/master/Work%20Practices/Accessibility%20and%20508
    • This makes it hard for people to read Github URLs and even harder to type them (e.g., if you're on your mobile device).
  2. Use meaningful descriptive titles for files (and folders).
    • Give files (and folders) descriptive names to help people understand what's in them before they click into them.
    • Avoid acronyms in titles. Characters are cheap. Use them!
    • Descriptive titles make it much easier to find things using Github's Search function.
  3. Include a useful README.md file at the root of your folder structure, e.g., inside your "Product/Design" folder.
    • Useful READMEs tell people what's in the sub-folders and files before they click into them.
    • Consider a TOC approach - here's an example
  4. Use a predictable folder structure.
    • Follow examples set by people/teams who came before you. Browse around in vets.gov-team repo to see what other teams have done.
    • Don't make a bunch of sub-folders that each only contain a few files. This makes it much harder for people to find things.
  5. When a folder contains 12 or more files, start thinking about grouping files into sub-folders to make it easier for people to find stuff.

Managing agile workflow

Each Github repo has a section called "Issues." Learn about issues.

We use Zenhub with Github to turn the "Issues" section into an scrum board.

The "Issues" section of the va.gov-team repo is where all teams manage their Epics, User Stories, and agile workflow.

Get help with Github

  1. If you have problems using Github, check the Github FAQs for potential solutions.
  2. Ask in a Slack channel.