Navigation Menu

Skip to content

Instantly share code, notes, and snippets.

@jbjonesjr

jbjonesjr/getting-going-best-practices.md

Created May 2, 2018 19:57
Show Gist options
  • Star 32 You must be signed in to star a gist
  • Fork 14 You must be signed in to fork a gist
  • Save jbjonesjr/d4854be10e2df5e2f91c4b4928d8ec68 to your computer and use it in GitHub Desktop.
Save jbjonesjr/d4854be10e2df5e2f91c4b4928d8ec68 to your computer and use it in GitHub Desktop.
Download ZIP
Getting Going and Best Practices Guide
Raw
getting-going-best-practices.md

GitHub Onboarding and Introduction

A guide for getting started and best practices for teams new to, or improving their interactions with, GitHub

image GitHub's features and capabilities

This document is meant to help new teams to GitHub familiarize themselves with the features and platform, as well as start to explore some of the best practices. While not a complete exploration, it's meant as a introduction to the key tenets of using GitHub for your business. For teams and organizations that desire more one on one support, GitHub Professional Services has many different options available to customize tools, training, and process to best meet your needs. The GitHub offerings listed in the diagram above are just a sampling of the various capabilities and we'd love to create a customized offering to meet your specific organizational needs.

Overview and Introduction

💻 Introduction to Git

Get familiarized with why modern distributed version control is an improvement over traditional centralized version control

🔑 :folder: Get Organized

Understanding the basis of how GitHub organizes and protects your data is key to collaborating with each other in a secure manner. This starts with understanding the tools GitHub gives you to manage communication, contribution, and administration.

image

REPOSITORIES

Repositories are the core workset within GitHub. They often represent a microservice, set of documentation, shell script or web app (or all of that in one!). Repositories can have visibilities that determine how wide they can be consumed, and a set of collaborators that specify who has editing ability to the information.

More details (help.github.com)
Understanding Repository Visibility
Public

If a repository is public, everyone who has access to your GitHub instance has access to view and clone the repository and read all Issues and Pull Requests. With a GitHub user account, they can also open Issues, join discussions, and fork the repository, but won't be able to modify any of the files directly. Push access to repositories is granted by adding users as collaborators, or, in the case of organization members, assigning write permissions to members or teams.

Private

Private repositories are only visible to the members(users) of that users or organizations. An organization can configure a default repository permission that gets applied to all members, but users can be granted more explicit permissions through their membership in a relevant team.

INDIVIDUALS

Every (contributing) member of your agency will need an individual user account in GitHub Enterprise instance. This account includes a personal workspace for repositories owned only by that user. Other users on GitHub can be granted write access to personal repositories by adding them as a collaborator

ORGANIZATIONS

Organizations allow users to share ownership and administration for a group of repositories. They help developers collaborate by providing a shared workspace to coordinate on projects, and practical permissions tools to make sure the right people have access to the right repositories.

Outside Collaborators

You can grant access to repositories to users who are not part of an organization by making them Outside Collaborators. Each repository maintains a list of these externally approved users for easy auditing. This allows you to collaborate with any user on GitHub without giving them access to the rest of the data in your Organization.

More details (help.github.com)

TEAMS

Teams allow you to communicate with groups of users and manage their access within a GitHub Organization. This can enable collaboration by giving groups of users read, write, or admin access to a repository in a single step. When you @mention a team in an Issue or Pull Request, all members of the team will be notified of the conversation.

Team Administration

Within a team, the Team Maintainer role gives users elevated privileges that are scoped to the team itself. These permissions include the ability to add a member to the team, promoting existing members to the Team Maintainer role, or changing a team’s permissions for any organization repository.

More details (help.github.com)

🌊 Get Flowing

Pull Requests, a GitHub invention since standardized on by almost ever tool in the industry, is the way that quality software gets built within GitHub. A Pull Request allows work to be grouped, discussed, reviewed, and tested all with transparent updates and collaboration. It's the cornerstone that many other GitHub features are built on.

About Pull Requests | Mentioning users and teams | About branches | About commits | About commit statuses | About pull request reviews | About commit statuses | About pull request merges

GitHub Flow & Protected Branches

GitHub Flow is the process around using Pull Request-based workflows to control changes to Github Repositories. This includes security and process definition, proper collaboration with discussions and code reviews, and insights on your code from external tools and integrations. The GitHub Flow is the central piece to the organizational and development maturity GitHub brings to bear. Protected Branches are how you can enforce these standards and procedures on the GitHub/Pull Request workflow. This helps to ensure the highest quality of code while meeting your organizations compliance requirements.

image

Understanding the GitHub Flow | About protected branches | About required status checks | 🎉 About required reviewers 🎉 | 🎉 About code owners 🎉 | About branch restrictions

🔩 Get Connected

New to Git and/or GitHub? Interacting is easy, either via the web interface or one of the many client tools. Below are a handful of tools that we've seen help new users get setup for the first time

✅ Get Managing

Get your work and projects managed from start to finish on GitHub

Describing and discussing work:

Planning and tracking work:

Best Practices

GitHub Enterprise Instance-wide Best Practices

  • All work-relevant repositories should be housed within an Organization. Personal repositories should be reserved for forks and temporary working activities (these repositories are not maintained if a user is off-boarded from the instance).
  • Organizations should be considered the public face of a business unit. As such, the organizations should have easy to discover names and default member permissions to Read so that all appropriate members have access to all public and private repositories held within.
  • Remember that all Instance members (but not outside collaborators) can see all public repositories in any Organization, regardless of membership.

Organization and Team best practices

  • The optimal count of Organizations varies depending on the instance size.
    • Get too many users in organization, and it becomes hard to collaborate and discovery.
    • Create too many organizations, and you've created siloed environment that discourages collaboration and increases friction to modern software development practices. This also increases the administration overhead.
    • A good example of this strategy is to look at the GitHub.com presence of organizations like Microsoft and Google who use as few organizations as possible for shared ownership of repositories and making use of teams to segment users within those organizations
VA suggestion
Based on the onboarding documentation previously provided, I might suggest creating Organizations that map to either EPMO portfolio or Delivery Pillar as these are already natural segregations of the agency.
I personally don't have enough information to suggest which one of those two attributes would make the most sense to divide by (my hunch is portfolio)

  • For each organization created, some customers find it helpful to create a sibling organization that contains data that should only be available to Organization members.

    • As previously mentioned, all public repositories are accessible to anyone with a GitHub account.
    • The previous organization default permission of Read means that all organization members can read all private repositories held within.
    • The sibling organization would instead use a default permission of None, and hold only private repositories that should only be accessible to a subset of Organization members. This is preferred to a proliferation of Organizations for this subgroups.
    • If the leading Organization is named Component, use a convention such as Component-Internal to name the sibling.
    • Team structures should be the same between the two Organizations (you can use the API to keep the sibling in sync with the leader).
    • A slightly more complex but user-simpler solution is to use a single Organization (versus sibling pairs), a default permission of None, but then maintain an organization-core team that has Read access to many of the private repositories. This lets you maintain the least access qualities of the sibling organization while only maintaining a single Organization and only introducing limited administrative overhead.

  • When doing cross organization collaboration, consider the design of teams vs outside collaborators. While not an exact science, the presence of more than one user who is collaborating externally on the same thing typically constitues creating a new team. Otherwise, outside collaborator access to a repository is likely easier to manage.

  • Standardize on naming conventions and organizational structures can help to make information much more discoverable.

    • Each top level product should have a team and a repository. This repository can be used for coordination (GitHub Projects and general issues), and the team as a handy notification for announcements to everyone involved.
    • prd-{product name} is an example of a standardized repo and team name for this top level group.
    • All microservices or components of a product should be an extension to this naming structure (prd-{productname}-{componentname}).
    VA example
    prd-vets.gov-cloudformationtemplates
    • This sort of naming conventions helps prevent name space collisions.

  • Depending on a components makeup, it might warrant a single team to correspond to it, or instead might be one of many repositories managed by a single team.

VA example
prd-vets.gov-infra
  • Teams should cross-cut products to focus on subject matters as well. (ex: a team can be formed for oracle-dbas which can include members from across the agency, providing great access to expertise).

General GitHub guidance on Organzation structure: Organizing People for Successful Collaboration (5 min video)

Repository best practices

  • All repositories should include a description and README.md to reduce confusion and improve discoverability.
  • All Product repositories should include how to contact the team, product management, links to things like roadmap, project management schedules, and the like. Issues and discussions should be scoped to high level, cross team activity (although having individual teams maintain their roadmaps and visible docs in this repository is not an anti-pattern).
  • Each repository that expects interaction should create a CONTRIBUTING.md file that defines the process and expectations for interacting with the repository.
  • Additional metadata files can be standarized on by your Business to describe common structure (Enterprise Asset Management ID, Project Manager Name, Link to Enterprise ticketing sysetm, etc).

📚 Get Documented

Get information about your work and projects documented to share right next to your code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment