15 tips for working with Github

Original author: Gabo Esquivel
  • Transfer
  • Tutorial

I have been developing software for 10 years, participated in several open source projects and in numerous non-open source projects, worked in large and small teams, and everywhere we used Github as a versioning repository.

During this time I tried different workflows, and I want to share tips on how to build an effective and pragmatic workflow for creating and maintaining high-quality software that can be used in any project.

There are many signs of quality software: reliability, stability, modularity, security, performance, scalability, ease of use, testing and maintenance. And many other signs, depending on the type of application. In this article, I will focus on the following properties:

  • Good documentation: readme, documentation sites, and change logs.
  • Detailed agreements and coding standards.
  • Correct versioning using semantic versioning.
  • Automated tests: we use not too many of them, we will focus on functional non-regression tests.
  • Of course, the happiness of the developer!

I propose building a pragmatic workflow using open source tools to help you perform and automate many tasks.

If you work in an open source project, then you probably want to publish your Github project. Git and Github completely changed the way OSS was developed, de facto becoming, respectively, the standard versioning language and platform for collaboration.

The workflow officially proposed by Github is called github flow . It is beautifully described on the site . This process, with slight variations, is followed by most open source projects.

Github Flow is very flexible in the sense that it does not dictate to you how to release and document changes, what merge strategy to use, when to accept pull requests, what tools to use, what commit standards to follow or what you need to review before accepting a pull request ' a. All this is at your discretion, and correctly done, since there are no universal solutions suitable for all teams.

Next, I will give a list of recommendations based on my experience.

For the most part (almost exclusively) I write in JavaScript, many of the tools I mentioned are part of the JS ecosystem, but the ideas themselves are applicable in any language.

Prioritize tasks and track progress with Github Projects


In September 2016, the Projects feature appeared. This is a tool that allows you to create Kanban-style boards to organize, prioritize, and track work at the repository and organization level. If you have difficulty using Github, I highly recommend mastering Projects to organize and share information on project priorities and ongoing efforts.

More details

Classify tasks using tags


Github has excellent filtering capabilities. If you are working on an open source project, then you are probably interested in attracting other participants, as well as in making it convenient for them. If you tag your tasks with tags, it will be easier for developers to navigate in the list, this will save them time and facilitate the work on the project.

Use github templates for pull requests and tasks


Take the time to write Guthub templates for pull requests and reporting problems. This will force other developers - or at least help them - to send bug reports and request the creation of features in some standard way, applying all the information you need.

More Details

Top tips for bug reports :

Before submitting problem information:

  • Make sure you are using the latest version.
  • Look for a mention of this bug, perhaps the report on it was already earlier.

Bug reports should contain:

  • Short description.
  • How did you encounter a bug? Playback Instructions.
  • What behavior did you expect from the application?
  • How did the application really behave?
  • Links to all tickets related to the situation or information sources.
  • If possible, attach a visual confirmation of the bug. Screenshots, videos and / or animated gifs.

General recommendations for pull requests :

  • Check that there are no other pull requests for your problem.
  • Check the bug tracker to see if there were any problems with your bug.
  • Non-trivial changes are best discussed in advance.
  • Let us know what task you are working on.
  • Develop in a specific thematic branch, and not in the wizard.
  • Write a description of the useful pull request.
  • Follow the recommendations for commits in the project.
  • Write a good description of your pull request.
  • Specify a link to the Github task in the description.

Use command line


The console is your friend. In my experience, mastering Github through the command line is the best waste of time when working with open source technologies. Yes, there are many good GUIs, but they are all less flexible to use. In addition, there are tools only for the command line, which greatly simplify life and increase development efficiency:

  • hub is a wrapper for Git that makes working with GitHub easier. It doesn’t matter if you are a beginner or an experienced open source developer, hub will make it easier to retrieve repositories, navigate project pages, work with forks and even send pull requests. And all this from the command line. hub.github.com
  • tj / git-extras - a set of Git utilities, such as a summary of the repository, repl, change log, statistics of commits by authors, and much more. github.com/tj/git-extras

Follow strict commit message standards and categorize commits


Always define and maintain clear standards for writing commit messages. Here are some guidelines:

  • Commit each commit as a separate change.
  • Write useful commit messages.
  • Write a short commit message in the first line (50-100 characters). If you look at the result of execution gitk or git log –oneline, you will understand why.
  • Link to the Git task in the body of the commit message.

In addition, to improve change log generation, I highly recommend categorizing messages (scope). Then your change logs will be more informative. A great example: commit committing and generating change logs in AngularJS .

Define code layout standards and configure pre-commit hooks


To write code that is convenient to maintain, it is very important to determine the design standards and follow them in pre-commits hooks. Standards will help maintain code uniformity regardless of who writes it, and will also help to accept and maintain code written by someone else.

I recommend using Prettier and StandardJS, but this is a matter of taste, there are many other solutions; besides, you can do something of your own. The main thing is to follow the selected standards for the design of the code, this will benefit.

typicode / husky is a great tool for configuring precommit hooks.

Use automated tests and pull request checks


It is highly desirable to automate functional tests and security checks and code style in each pull request. It is unlikely that you will want to do all this manually. You can quickly configure a continuous integration server, such as TravisCI, to automatically run a topic branch through tests after sending each pull request. You can also configure Github to prevent the developer from attaching pull requests if they fail the tests. If the tests fail, Github will show the author a message so that he can fix his pull requests.

More details .

Protect your master branch and require code revision


Github allows you to protect the master branch from direct commits, forced push'ey and rebase. This is very important when you are working with someone on a project. In addition, be sure to require a revision of the code before combining it with the master branch. This is set in the settings tab of each repository.

Having protected the master branch and enabled forced revision, you will know that unwanted code is unlikely to get into the master and that no one in the team will substitute the rest by changing the Git history of the master branch or by running an unverified code.

Squash your pull requests


There is much debate about what is right: combine, squash, or rebase. I think it’s best to squash because:

  • Not all developers know how to correctly rebase pull request over the master branch. Many simply blame the master on top of their changes. Squashing allows you to get rid of merge-messages, which are useless for the future formation of the change log and simply make noise in the Git-log.
  • Not all project participants will follow the recommendations for making commits, and squashing allows you to manage the commit messages received in the master branch.

To successfully build a squash-based workflow, you need to categorize all pull requests by specific features, bug fixes, or routine tasks.

Semantic versioning, Github tags, releases, and automated change logs
Versioning plays a huge role, especially in open source projects, many of which will depend on your software. Semantic versioning will make life easier for everyone, because people, just by looking at the version number, will know exactly when the critical changes were made, or whether the version contains new features or bug fixes.

Given the template MAJOR.MINOR.PATCH, increase:

  • An older (MAJOR) version if you make changes to the API that are incompatible with previous versions.
  • Minor (MINOR) version if you add backward compatible functionality.
  • Patch version (PATCH) if you make backward compatible bug fixes.

As extensions of the MAJOR.MINOR.PATCH template, you can use additional tags for prerelease and assembly.

In addition to changing the version of package.json, I recommend generating a git tag for each version.

More details .

The Conventional Commits specification implies compliance with a simple, standardized agreement when writing commits. It is linked to the SemVer agreement, which asks developers to describe all features, fixes, and critical changes in commit messages. Following the agreement, we create a standard language that simplifies debugging in various projects.

More details .

Automate this process will help TravisCI .

Also pay attention to these packages:dominique-mueller / automatic-release , semantic-release / semantic-release .

Automate deployment with tag hooks


It is not necessary to use release branches, as suggested by Git Flow. You can take deployment artifacts from Git tags. Here's how to deploy Git tags to heroku using TravisCI . It is very simple, you just need to set the tag attribute to true. This behavior can be implemented using any other CI server.

For the development environment, you can configure a hook that deploys the last master commit. And for feature environments, you can use not-so-long-lived branches; if you wish, for each PR request you can provide a temporary test environment, but this approach is more complicated, and is not required.

Set up a live github feed for chat


A very convenient way to track activity in your Github repositories from a place ideally suited for interacting with the team: a simple stream of notifications in one or more chats. By the way, in chats you can do much more, in 2013 the term ChatOps appeared on Github , more about it is described here .

Automate dependency updates


We have to regularly spend a lot of time updating dependencies. This is an ideal task for automation. There are many tools to help keep dependencies fresh by automatically creating pull requests in the project with the latest versions. These queries will be driven through automated non-regression tests, and if they succeed, then we can hope that the code will work fine after the merge. Be careful with changes in the level of older versions, double-check everything.

A couple of useful tools: greenkeeper.io and david-dm.org .

Enhance Github’s UI with Extensions


Open source developers have created many useful extensions that improve the work with the Github interface. For instance:


Other extensions: GitHub Browser Extensions .

There are more tools on Kikobeats / awesome-Github to improve your workflow.

Continuous study and self-improvement


Github and open source software development techniques are constantly evolving, so keep abreast of the latest trends and tools by monitoring Github news and following your community’s standards. A great source of information is the GitHub Training & Guides Youtube channel .

Also popular now: