Enhancing Your GitHub Workflow

August 8, 2018 (6y ago)

With a decade of experience in software development, I've had the privilege of contributing to various open source and non-open source projects using GitHub. Today, I'd like to share an effective and practical workflow that can enhance the quality of your software, applicable to any project.

Key aspects of quality software include robustness, testability, modularity, maintainability, and more. In this article, I'll primarily focus on:

  • Comprehensive documentation: READMEs, documentation sites, and changelogs.
  • Clear coding standards and conventions.
  • Semantic versioning (SemVer).
  • Automated tests, with an emphasis on functional non-regression tests.
  • An excellent developer experience.

To achieve these goals, I propose a pragmatic GitHub workflow that leverages open-source tools to automate essential tasks.

If you're involved in an open-source project, publishing it on GitHub is a must. GitHub has transformed open-source development by becoming the go-to platform for version control and collaboration.

GitHub offers great flexibility, allowing each project to define its release and documentation processes, merge strategies, preferred tools, commit standards, and code review practices tailored to their needs. This adaptability recognizes that there's no one-size-fits-all solution for every team.

Here are some recommendations based on my experience:

Prioritize and Track Progress with GitHub Projects

Utilize GitHub Projects, introduced in September 2016, to organize, prioritize, and track your work. It enables you to create Kanban-style boards for efficient project and organization-level task management. If you're using GitHub issues, this feature can greatly enhance project organization and communication. Learn more.

Classify Issues with Tags

Tagging your GitHub issues simplifies navigation for developers and encourages collaboration. By tagging issues, you reduce entry friction, making it easier for contributors to get involved.

Leverage GitHub Templates for Pull Requests and Issues

Creating GitHub templates for issues and pull requests streamlines the bug reporting and feature request process, ensuring that developers provide all necessary information. Check out GitHub's guide for details.

Use the Command Line

Mastering GitHub's command-line interface provides flexibility and efficiency when working with open-source technologies. Tools like hub and git-extras enhance your experience and productivity. hub simplifies GitHub interactions, while git-extras offers various Git utilities.

Follow Clear Commit Message Standards (Scoped Commits)

Define and adhere to clear commit message standards. Ensure each fix is a separate change, provide concise commit messages, and reference related issues. Scoping your messages aids in generating informative changelogs. The AngularJS commit conventions offer a great example. Learn more.

Define Coding Style Standards and Set Up Pre-commit Hooks

Maintain code consistency by defining coding standards and enforcing them with pre-commit hooks. Using tools like Prettier and StandardJS (or others of your choice) ensures uniform code formatting. husky is a valuable tool for configuring pre-commit hooks.

Configure Automated Tests and Checks on Pull Requests

Implement automated functional tests, security checks, and code style verification for every pull request. Configure continuous integration with tools like Travis CI to run tests automatically and prevent merging if checks fail. Learn more.

Protect Your Master Branch and Require Code Reviews

Safeguard your master branch from direct commits and enforce code reviews to ensure code quality. GitHub provides settings to enable these protections in your repository.

Squash Your Pull Requests

Consider squash merging as it simplifies your Git history and eliminates merge noise. This approach is especially valuable when not all contributors follow commit guidelines.

Semantic Versioning, GitHub Tags, Releases, and Automated Changelogs

Embrace semantic versioning (SemVer) for clarity in versioning. Create Git tags for each version to help users understand changes easily. Integrating Conventional Commits enhances changelog generation. Travis CI can automate this process. Learn more and Conventional Commits.

Automate Deployments with Tag Hooks

Instead of using release branches, deploy directly from Git tags. Tools like Travis CI simplify the process, allowing you to deploy to platforms like Heroku. Configure hooks to deploy the latest master commit for development environments.

Set Up a GitHub Stream Channel in Your Chat Room

Track GitHub activity conveniently by integrating notifications into your team's chat room. This is known as ChatOps and streamlines communication. Learn more.

Automate Dependency Updates

Automate the task of keeping dependencies up to date using tools like Greenkeeper.io and david-dm.org. These tools create pull requests with updated versions, which can be tested automatically to ensure compatibility.

Enhance Your GitHub UI Experience with Extensions

Explore extensions that improve your GitHub experience, such as GitHub Avatars, GitHub Awesome Autocomplete, GitHub Hovercard, and more. These extensions enhance various aspects of GitHub's user interface.

Continuous Learning and Improvement

Stay up to date with GitHub's evolving practices and tools. Regularly check GitHub announcements, community standards, and GitHub Training & Guides on YouTube for valuable insights. GitHub Training & Guides on YouTube.

title: Recommendations to Enhance your Github Flow publishedAt: 2018-08-08 summary: An opinionated list of tips to enhance your workflow on Github.

I’ve been working on software development for 10 years now and along the way, I’ve had the opportunity to collaborate on several open source projects and also worked on many non-open source projects where we used Github as our version control repository, on small and large teams.

On my journey, I’ve followed different workflows depending on the project and today I want to share with you what I consider to be a effective and pragmatic workflow for building and maintaining good quality software that can be applied to any project.

The attributes of good quality software are many: robustness, testability, resilience, modularity, maintainability, usability, security, performance, scalability and more depending on the type of application you are building. On this article I’ll mainly focus on the following characteristics:

  • Good documentation: readme, documentation sites, and changelogs.
  • Well defined coding standards and conventions.
  • Proper versioning with semver.
  • Automated tests: not too many, focus on functional non-regression tests.
  • Good developer experience, sure!

To accomplish this I’m proposing a pragmatic Github flow leveraging open source tools that help facilitate and automate many of the tasks required to achieve this goal.

If you are working on an open source project you want to publish your project Github, that’s a fact. Git and Github have radically changed the way OSS is developed by becoming the de-facto common language for version control and definitive place for collaboration respectively.

The official workflow proposed by Github is called github flow and it’s very well documented on their website guides.github.com/introduction/flow, most open source projects follow this workflow with slightly different flavors.

Github Flow

The Github workflow is very flexible in the sense that it doesn’t tell you how to release and document changes, what merge strategy to use when accepting pull request, what tools to use, what commit standards to follow or what to review before accepting a pull request, that’s up you and that makes a lot a of sense since there’s no universal solution for every team’s needs.

The following is a list of recommendations based on my experience:

I work mainly ( almost exclusively ) in JavaScript, many of the tools I’ll mention are part of JS ecosystem, however, the principles apply to any language.

Prioritize your Issues and Track your Progress with Github Projects

In September 2016 Projects feature was launched. It is tool allows you to create kanban style boards to organize, prioritize and track your work at the repository and organization level. If you use Github issues I strongly suggest you make use of the feature for organizing and communicating better the priorities of the project and the current efforts. You can learn more on the following link help.github.com/articles/tracking-the-progress-of-your-work-with-project-boards

Classify your Issues with Tags

Github provides great filtering functionalities. If you are working on an open source project you want people to collaborate on your project as well as provide a good experience to the developers using it. By tagging your issues developers will able to more easily navigate the issue list, saving them time and allowing them to contribute with less entry friction.

Leverage Github Templates for Pull Request and Issues

Taking the time to write Github templates for your issues and pull request will certainly pay off; This will force or at least help developers to report bugs and request features in the standard way with all the information you need to address them.

Learn more at blog.github.com/2016-02-17-issue-and-pull-request-templates

Some general guidelines for bug reports:

Before submitting an issue please check that you’ve completed the following steps:

  • Made sure you’re on the latest version
  • Used the search feature to ensure that the bug hasn’t been reported before

Bug reports should contain the following information:

Summary: A brief description. Steps to reproduce: How did you encounter the bug? Instructions to reproduce it. Expected behavior: How did you expect it to behave? Actual behavior: How did it actually behave? References: Links to any related tickets or information sources. If possible, attach visual documentation of the bug. Screenshots, video and/or animated gifs.

Pull Request General Guidelines:

  • Please make sure that there aren’t existing pull requests attempting to address the issue mentioned.
  • Check for related issues on the issue tracker.
  • Non-trivial changes should be discussed on an issue first.
  • Let us know you’re working on the issue.
  • Develop in a topic branch, not master.
  • Provide useful pull request description.
  • Follow project commit guidelines.
  • Write a good description of your PR.
  • Link to the Github issue in the description.

Use the Command Line

The console is your friend. In my experience learning to interact with Github from the command line is the best use of your time if you work with open source technologies. There are many nice GUIs, however, none of them will give the flexibility of the command line. There’s also tooling that will make life much simpler and a more efficient developer that is only available for the command line:

  • hub is a command-line wrapper for git that makes you better at GitHub. Whether you are a beginner or an experienced contributor to open-source, hub makes it easier to fetch repositories, navigate project pages, fork repos and even submit pull requests, all from the command-line. hub.github.com
  • tj/git-extras is a set of git utilities such as repo summary, repl, changelog population, author commit percentages and more. github.com/tj/git-extras

Follow Strict Commit Message Standards ( Scoped Commits )

Always define and follow clear commit message standards for your projects, some general guidelines are:

  • Commit each fix as a separate change.
  • Provide useful commit messages.
  • Provide a short commit message in the first line (50-100 character). Looking at the output of gitk or git log --oneline might help you understand why.
  • Reference the git issue on the body of your commit message.
  • Additionally, I strongly suggest you scope your messages for a better changelog generation. When you scope your messages your changelogs can be more informative. The AngularJS commit conventions and changelog generation is a great example gist.github.com/stephenparish/9941e89d80e2bc58a153#generating-changelogmd

Define Coding Style Standards and Configure Pre-commit Hooks

Defining coding standards and enforce them through pre-commits hooks is essential for writing maintainable code. By following these standards you make sure all code looks the same regardless who wrote it, facilitating taking over and maintaining code written by someone else.

My recommended setup is Prettier and StandardJS, however, that’s a matter of preference, there are many others and you can also configure a custom one, as long as you follow a coding standard you will benefit.

typicode/husky is a great tool to configure pre-commit hooks.

Configure Automated Tests and Checks on Pull Requests

Automated functional tests, security and code style checks against every pull request are highly desirable, you don’t want to do it manually. A continuous integration server such as TravisCI can be quickly configured to run these test automatically against the topic branch every time a pull request is submitted and Github can be configured to prevent the developer from merging pull requests that don’t pass these test. If these automated tests fail Github will display a message on the pull request for the requester to fix them.

Learn more at docs.travis-ci.com/user/pull-requests

Protect Your Master Branch and Require Code Reviews

Github gives you the possibility to protect your master branch against direct commits, forced pushes and rebase. This is very important when collaborating with others on a project. Additionally, you want code reviews as required step in order to merge code into master. By configuring this on the settings tab of each repository.

By protecting master and enforcing code reviews you are going peace of mind that it’ll be unlikely that undesired code will land in master and the no one in the team will affect others modifying the master git history or pushing unreviewed code.

Squash Your Pull Requests

This is a hot debate: Merge vs Squash vs rebase. I believe squash merge is the best approach for the following reasons:

  • not all developers know how to properly rebase a pull request on top of master, that’s a fact. Many developers will simply merge master on top of their changes. Squash merge gets rid of those merge messages that are useless to construct a changelog later and add noise to the git log.
  • not all contributors will follow the commit guidelines, squash merge allows to control the commit message that land in the master branch. In order to follow a squash merge workflow successfully it is necessary that every pull request is scoped to a specific feature, bug fix or chore.

Semver, Github Tags, Releases and Automated Changelogs

Versioning is super important in software and especially in open source projects where a lot of projects will depend on your software. Semantic versioning will make life easier for everyone as they will know exactly when breaking changes where added or if a new version contains a new feature or a bug fix, by just looking the version numbers.

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backward-compatible manner, and
  • PATCH version when you make backward-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

In addition to changing your package.json version generating a git tag for each version is a good practice.

Learn more at semver.org.

The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages. This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make.

By introducing this convention, we create a common language that makes it easier to debug issues across project boundaries.


TravisCI can help to automate this process docs.travis-ci.com/user/deployment/releases

You may also found these packages useful dominique-mueller/automatic-release, semantic-release/semantic-release.

Automate Deployments with Tag Hooks

It’s not necessary to use release branches as proposed on GitFlow. You take the deployment artifact from your git tags; In the link you will learn more about how to deploy git tags to heroku using TravisCI docs.travis-ci.com/user/deployment/heroku. It’s very simple, you just need to set the tags attribute to true. You can accomplish the same behavior with any other CI server.

For a development environment you can setup hook that deploys the latest master commit and for feature environments, it’s ok to have not so long living branches, optionally you could provision ephemeral test environments for each PR request, however, this is more complex and not really required.

Setup a Github Stream Channel on Your Chat Room

This is a very convenient way to track the activity on your Github repositories from a single place, the place where you communicate with your team is ideal. These are simple notifications stream on a topic room or several ones. But there much more you could do on your chat rooms, in 2013 Github coined the term ChatOps, you can learn about it here youtube.com/watch?v=NST3u-GjjFw

Automate Dependency Updates

Keeping your dependencies up to date is time-consuming and repetitive task, ideal for automation. Luckily there are many tools that will help you keep your dependencies updated by automatically creating pull requests on your project with the latest versions, your automated non-regression tests will run against that pull request and if it passes chances are your code will continue to work normally once you merge it. Be careful with major version changes, always double check.

A couple tools that will help you are greenkeeper.io and david-dm.org

Enhance your Github UI Experience with Extensions

Open source developers have built many useful extensions that enhance your Github’s experience, here’s a list you may find useful.

  • GitHub Avatars - Display avatars in GitHub news feed.
  • GitHub Awesome Autocomplete – Add instant search capabilities to GitHub search box.
  • GitHub Categoric – Categorize your mixed GitHub notifications.
  • GitHub Hovercard - Neat user/repo/issue hovercard for GitHub.
  • GitHub Isometric Contributions – Render an isometric pixel art version of your GitHub contribution graph.
  • GitHub Linker – Link dependencies in a package or bower file to their GitHub page.
  • GitHub Octotree – Display GitHub code in tree format.
  • GitHub Selfies – Add selfies to your pull requests and comments on GitHub.
  • GitHub Stars Tagger – Add tags to your starred repositories directly on GitHub.
  • Github NPM Hub - Explore npm dependencies on GitHub repos
  • Github vscode-icons show vscode-icons in the repository browser.

You can see more on GitHub Browser Extensions.

Kikobeats/awesome-Github has more tooling you leverage to improve your github flow.

Continuous Learning and Improvement

Github and open source software development practices are constantly and rapidly evolving, keep up to date with latest practices and tooling by following Github announcements and following your community standards and practices. GitHub Training & Guides channel on youtube is a great resource. youtube.com/githubguides