This repository is home to all of the team's project issues. Once you create an issue on this repository, it becomes available to be added to one of our team's projects. If you're creating an issue to link it to a team project, start the issue title with the project name.
This repository is also home to all of our GitHub standards. Read on for information on getting added to the team, creating repositories, contributing to repositories, creating issues and projects, and more.
Git and GitHub can seem bewildering at first. This documenation will simplify and clarify common workflows and provide our team with a standard way of doing things together.
Each user must:
- Activate 2-factor Authentication
- Add your information to your account, including:
- Name: Your first or first and last name.
- Company: Your government agency.
- Location: Your primary work location (City, State).
- Email: A valid email address.
- Add a profile avatar
- Make your membership public by going to the team page, finding yourself, and clicking Make Public.
A repository corresponds to a single project. If the project is an annually recurring one, then you can simply create folders within that repository for the different iterations.
Each repository should:
- Be public by default, although it is possible to create private repositories (see notes below).
- Have a simple and useful name that corresponds to both its Slack channel and its Google Drive folder in the team drive.
- Avoid acronyms and clever names/puns as those can make it hard to search for projects.
- If the repo is for a cross-project utility (e.g. a Qualtrics API script), use a descriptive name that describes what the project does.
- Have a user-friendly description
- The description of a repo tells the public what is contained in the repo itself. If you have multiple repositories for the same project, it's better to describe what is contained in the repo itself instead of describing the project.
- Repo descriptions should be clear, concise, and descriptive. Descriptions are listed under each repository title on an organization’s GitHub page. Anyone who scans the GitHub page should be able to determine what a repo does, just by looking at the description
- Have a useful README.md (see below)
Standards for making a private repo: By default, projects in GitHub.com/GSA should be public. They should only be made private under certain circumstances.
A repository can be made private if it contains information that legally cannot be made public.
Our team can give members administrative, write, or read permissions.
Even if you have write access into a repository, we strongly encourage the submission of pull requests for improvements or fixes as this providers other collaborators and opportunity to review/comment on your edits.
Two common ways to document a project are README files and wikis:
- README files are a quick and simple way for other users to learn more about your work.
- Wikis on GitHub help you present in-depth information about your project in a useful way.
It’s a good idea to at least have a README on your project, because it’s the first thing many people will read when they first enter the repository. You're actually reading this repo's README right now! So, when you create a new repository, select “Initialize this repository with a README” unless you plan to import an existing repository.
Within this repo, there's a README-Template.MD that you can use to help get you started.
You can read more about creating a README (or Wiki) in the official GitHub documentation here.
If it's a public repository, it's a good idea to codify contributing guidelines. A common practice is to use Github Flow, so all code changes happen through pull requests. With pull requests, it's easy to follow the shared repository model.
GSA employees can use the the shared repository model. In the shared repository model, collaborators are granted push access to a single shared repository and topic branches are created when changes need to be made. Pull requests are useful in this model as they initiate code review and general discussion about a set of changes before the changes are merged into the main development branch.
CONTRIBUTING.MD describes this model in greater detail. You can also read more about contributing guidelines in the official GitHub documentation here.
Issues are a great way to keep track of tasks, enhancements, and bugs for your projects. They’re kind of like email — except they can be shared and discussed with the rest of your team. Most software projects have a bug tracker of some kind. GitHub’s tracker is called Issues, and has its own section in every repository.
Within this repo, there's an ISSUE-Template.MD file with a basic bug/enhancement template. You can use this to populate your repo with a pre-built issue templates. Or you can create issue templates from within your repository using the issue template builder. Either way, these templates will be available for contributors to use when they open new issues in the repository.
You can read more about issues in the official GitHub documentation here.
If you add a pull request template to your repository, project contributors will automatically see the template's contents in the pull request body. As a team, we haven't decided if we want to do this yet. If we do, there's more to read here.
Project boards on GitHub help you organize and prioritize your work at a repository level. You can create project boards for specific feature work, comprehensive roadmaps, or even release checklists. With project boards, you have the flexibility to create customized workflows that suit your needs.
Project boards are made up of issues, pull requests, and notes that are categorized as cards in columns of your choosing. You can drag and drop or use keyboard shortcuts to reorder cards within a column, move cards from column to column, and change the order of columns.
Within this repo, there's a pre-built project board that you can copy to your repo.
You can read more about project boards in the official GitHub documentation here.
The license on every repo must be Creative Commons 0, or CC0. That’s shorthand for Public Domain. MD should be committed to working in the public domain by our own policies even though that is also required by law.
Within this repo, there's a LICENSE file that you can copy into the root of your repos.
You can read all about licenses here.