In Chapters 9 and 10, we describe best practices for both contributing and creating your own open source project. Here is the secret: Those best practices all apply to inner-sourcing as well. Even if you’re working on your code in private on a small team, it is still important to document, follow style guidelines, communicate effectively through issues and pull requests, provide applicable feedback through thorough code reviews, and be a positive team member.
When in doubt, pretend the world can see you.
In addition to following best practices for open source on your private projects, you can also leverage additional GitHub resources because your projects are within a private organization.
1. Repository insights
When you’re a part of a company, evaluating an engineer on their contributions to the team can get tricky. Either as an individual trying to make sure you’re making good progress or as a manager trying to write end-of-year reviews and performance ratings, you want to avoid using information to qualify someone’s overall contributions and performance.
That being said, you can get some information to help guide conversations to more effectively evaluate yourself or another individual. On a repository, you can click the Insights tab at the top right. You see a list of insights about your repository and the people that contribute to it:
» Pulse is a snapshot of your repository for a specific time period (defaulted to one week). For example, in the month of January, 2019 the Microsoft/VSCode project had the following pulse summary:
Excluding merges, 59 authors have pushed 1,028 commits to
master and 1,074 commits to all branches. On master, 1,045 files
have changed and there have been 28,273 additions and 21,574 deletions.
» Contributors shows an overall contribution graph for the repository, as well as individual contribution graphs for each contributor with a summary of the number commits, lines added, and lines removed.
Tracking contributions to a project simply by lines of code modified or number of commits isn’t an effective way to evaluate someone if nothing else is taken into account. For example, Shawn could commit every 15 minutes for fear of losing work, and Sam could always focus his energies on refactoring, making the number of lines of code he changes substantial. Comparing these two to Sandra, who had only a few commits and not as many lines of modified code but found and fixed a security vulnerability that could have taken down the application for good, isn’t a fair comparison.
» Community/Traffic: On public repositories, the community profile on a repository helps maintainers understand where they can improve their repository to better support their community. You can find out more at https://help.github.com/articles/about-community-profiles- for-public-repositories. On private repositories, the Traffic section gives you insight into who is coming to this repository, where they’re coming from, and what files they’re interacting with.
» Commits: This simple commit graph can give you insights into problems your repository may have or trends with the lives of your contributors. For example, if contributions drop off every year around May, maybe a school contributes to your repository a part of the curriculum. And if you typically have 300 commits a week but suddenly you start getting only 50 commits, maybe folks are running into a problem where they can’t get their code working well enough to commit.
» Code frequency: Similar to commits, code frequency shows the frequency at which lines of code are added and lines of code are deleted. Identifying patterns here can help you understand the health of your code as well as the profile of your contributors.
» Dependency graph: The dependency graph lists all dependencies (and dependents) of this repository and the version it depends on.
If you want GitHub to create a dependency graph for your private project and therefore be able to warn you if you have any dependency security vulnerabilities, you have to grant GitHub read-only access to your private repo (see Figure 11-13). (For more on dependency security vulnerabilities, read https://github. blog/2018-07-12-security-vulnerability-alerts-for-python/for the announcement on security vulnerability alerts for Python.)
» Alerts: On a private repository, you have an Alerts section. If you’ve enabled read-only access to GitHub either via allowing it through the dependency graph setting shown in Figure 11-13 or in the Settings tab for the repository in the Options category under Data Services, as shown in Figure 11-14, you will see security alerts here.
» Network: The network graph shows all the people that have branched and forked the repository and any branches of branches or forks of forks. Essentially, it shows all the possible states of your repository in the world today. Figure 11-15 shows the network graph for the GitHub package for the Atom editor.
» Forks: The Forks tab lists links to all forks of your repository.
2. Milestones for larger projects
Project boards are an effective way to track the progress you’re making through the issues and pull requests, but when you’re working as part of a larger organization, you will often have larger milestones that you’re trying to reach. GitHub provides support for milestones that can be linked to issues and pull requests.
To create a milestone:
- Go to the Issues tab of your repository and click the Milestones button.
If you don’t have a milestone yet, you can click the big, green New milestone button on the top right or the big, green Create a Milestone button in the center. This will take you to a new page where you can add a title and optional due date and optional description.
- Click Create milestone.
You see a list of milestones.
In your list of milestones, to the right of the one you just created, is a progress bar with a status of the percentage of issues and pull requests completed, the total number of issues and pull requests still open, and the total number of issues and pull requests already closed. This information can give you a quick snapshot of how close you are (or, in most cases, aren’t) to meeting your deadline.
On your Issues or Pull requests tabs, you can add the milestone to any issue or pull request, and the status icon on the milestone list updates automatically. Clicking the Milestone gives you a list of all the issues and pull requests associated with that particular milestone.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.