Contents


Overview

Skill Level: Any Skill Level

Social coding and open source software communities drive many of the standards adopted internally across companies. With the advent of GitHub Enterprise, this is more true now than ever, as the list of companies (of all sizes) adopting GHE grows.

Step-by-step

  1. Badges

    Badges are a quick way to provide info-at-a-glance for developers coming across your repository. They typically display information such as the code coverage, the current build status, whether or not its dependencies are out of date, and other useful information that tells the developer about the working state of the project.

     

    Example of Badges in repository README.md

    Badges are continually being provided for more and more types of information, and there is a service that generates these badges. Unfortunately for most enterprise developers, services like shields only work if your code is publicly hosted.

    However, there is still an alternative for purely internal repositories to get badges: GitHub pages (covered more in the next step). We can generate these badges ourselves and host them on Github pages using tools like the istanbul cobertura generator, which generates a XML file that is then read from to create the badge.

  2. GitHub Pages

    GitHub offers static pages alongside any repository. This can be any HTML/JS that you push to the branch gh-pages, so its left wonderfully open for your own purposes. GitHub pages can be used to store things like JSDocs, code coverage statistics and hosting badges.

    On top of that, it is easy to automatically update GH Pages with this info on push via Travis. Given the following snippet from a travis.yaml:


    after_script:
    - if [ "$TRAVIS_BRANCH" == "master" ]; then npm run gh-pages; fi

    Here a script is conditionally run if code is checked into the master branch. The script itself is straightforward, as well. This script was written in Node, but it could easily be written in something like bash.


    #!/usr/bin/env node
    "use strict";

    var sh = require("shelljs")
    , path = require("path")
    , pkg = require(path.join(sh.pwd(), "package.json"));

    var program = require("commander");

    program.parse(process.argv);

    // scope without @ becomes first slug in reponame
    var scope = pkg.name.split("/")[0];
    scope = scope.split("@")[1];

    // scope + - + name = repo name
    var name = pkg.name.split("/")[1];

    sh.echo("Getting artifacts..");
    if (!sh.test("-d", "./gh-pages/coverage/")) sh.exec("npm run coverage");
    if (!sh.test("-d", "./gh-pages/jsdoc/")) sh.exec("npm run jsdoc");

    sh.echo("Publishing to Github Pages");
    sh.pushd("gh-pages");

    sh.exec("git init");
    sh.exec("git config user.name "travis"");
    sh.exec("git config user.email "travis"");
    sh.exec("git add .");
    sh.exec("git commit -m "Publish to GH Pages"");
    sh.exec("git push --force "https://[User ID]:" + process.env.GHE_TOKEN + "@[GitHub Domain]/[GitHub Org]/"" + scope + "-" + name + " master:gh-pages");
    sh.echo("done like dinner");

    We use additional community tooling in istanbul, mocha, and jsdoc to build out the API docs and coverage reports in HTML format. From that point it is as simple as checking out the proper branch (gh-pages) and pushing the contents. We utilized a functional ID for this purpose so that we could uniformly apply this script across many repositories, but it could easily be done with an individuals GHE username and personal access token.

  3. Commitizen

    commitizen is a community project that helps development teams enforce commit conventions outlined in their contribution guidelines. Commitizen was born out of the commit conventions that the AngularJS team created to both make the history more easily readable and to enable them to automatically generate things such as the Angular changelog, but you can program it with any convention that you want to be enforced.

    By enforcing these commit conventions, commitizen builds up a wealth of metadata in your git commit history, which can be used for things ranging from intelligently following Semantic Versioning principles to automating documentation, work item closures, etc.

    commitizen is unobtrusive and only changes one piece of your workflow: “git commit” becomes “git cz”, which begins an interactive prompt that walks you through the details of your commit. Typically only the scope and a short description is required, but of course this is left up to the repository owner.

  4. Community Conventional Commit Tooling

    To expand on the specifics of things you can accomplish once you have configured commitizen:

    There is conventional change log for automatically writing a change log based on the commit data. This will do things like list bug fixes together, highlight breaking changes, and more.

    There is a conventional recommended bump tool that will actually recommend which semantic version increase you should apply to your library based on the commit data. This is useful because it means that you can fully automate your library release pipeline without having to worry about having an unintelligent or useless versioning history.

    If the tools that are out there do not satisfy your needs, then there are community parsers that you can build your functionality on top of, but the two tools I have linked here are really just the start of the community tooling already available to work for you out of the box.

    The possibilities around advanced project management are limitless once you establish a commit convention and enforce it consistently.

  5. Documentation Standards

    On GitHub, you can assume that any popular project will have at least two of the following files in it:

    • README.md
    • CONTRIBUTING.md

    These two files are a vital starting place for anyone that is new to a repository. The role of the README would likely be obvious to anyone, but CONTRIBUTING.md is the way that GitHub enables repository owners to enforce and define contribution guidelines so that anyone can participate. While managing previous projects such as Presence Insights, we initially had one set of contribution guidelines for all of our repositories and developers, but we found that over time that a one-size-fits-all approach simply did not work. Replacing that with repo level contribution guidelines defined by project owners and team leads, we found that developers had a much clearer idea of what was expected of them when contributing to a specific repo.

    GitHub will even gently remind users when they are opening a pull request against a repository that has defined a CONTRIBUTING.md:

Join The Discussion