What is GitHub?

GitHub is our software version control platform, as well as our CI/CD system (Continuous Integration/Continuous Deployment). GitHub is built on top of Git, a system that keeps track of every change made to our software. GitHub as a platform lets us create processes for developing new features, fixing bugs, with code reviews and automated testing.

While we use a graphical UI when creating pull requests and reviewing code in GitHub it is important that you learn to work with Git's command line interface locally. This is preferred because when you start off using Git in a graphical app locally, it's possible you're using Git's tools without fully understanding the underlying commands and what they do. This can result in unwanted merges and creating merge conflicts.

Merge conflits

Merge conflicts happen when the same block of code is edited  in a branch that wants to be merged and the branch it wants to merge into. Merge conflits need to be solved manually, line by line, and therefore we want to avoid merge conflicts as much as we can. Having a good understanding of Git's commands is essential for minimizing merge conflicts.

 

 
 

It is important you have a good understanding of Git, please read the following guides before continuing this guide, to make sure all of the git basics are fresh in your mind:


Feature branches

In all Git projects there is at least one "main" branch. This branch represents the current state of the software build and should always be deployable. If some code is merged into the made branch that breaks the product, this will interrupt work for all developers, because they will start new branches by copying code from the main branch.

In many Git projects the main branch is called "master" or "main". At DXPR we use multiple main branches that each refer to the corresponding main branches of Drupal core:

  • 1.x (For Drupal 8 and higher)
  • 7.x (For Drupal 7, a legacy Drupal version)

Branch naming convention

In the above documentation, you learned that feature branches are isolated branches in which developers can develop features without making changes to the main branch. In fact, this workflow is not just used for developing features, but also for fixing bugs. Bug fixes need to be tested in an isolated branch and only merged into the main branch when the fix is tested and validated.

Because our repositories have multiple main branches, this is reflected in our branch naming convention:

person/target-branch/#issue-description-of-branch

Here is a breakdown of the branch naming convention:

  • person — The name of the owner of the branch. For example Jur, Rokaya, Shaaer, Denis, etc.
  • target-branch — A reference to the target branch you want to merge into, for example, 1.x.
  • #issue — Every branch must be linked to a GitHub issue. Enter the issue number here.
  • description-of-branch — Describe what's inside, for example" fix-for-jumping-controls-bug or new-icon-set-for-parameter-definition.

Because our isolated branches are for more than just feature development we will call them Topic Branches from here on.

Example of a topic branch name: jur/1.x/#99-fix-for-jumping-controls-bug


Pull Request workflow

In the GitHub guide linked above, you have read about the "GitHub flow". This flow is essentially what a Pull Request workflow is. I will copy the six steps mentioned in the guide and elaborate the steps with DXPR specific conventions:

  • Create a branch: Topic branches created from the canonical deployment branch (1.x or 7.x) allow teams to contribute to many parallel efforts. Short-lived topic branches, in particular, keep teams focused and results in quick ships. Topic branches are created locally and pushed to the origin repository on GitHub. 
  • Add commits: Snapshots of development efforts within a branch create safe, revertible points in the project’s history. It is important all commits have a description of the code in the commit. To make pull requests more transparent and easier to review it is preferred to split up your code changes into isolated commits that represent increments of your work, rather than creating one big commit after days of coding.
  • Open a pull request: Pull requests publicize a project’s ongoing efforts and set the tone for a transparent development process. When opening a pull request we put keywords in the description and the issue number. If a topic branch fixes a bug, the description needs to include the fixes keyword and the #id of the issue that described the bug that is fixed. For example "Fixes #90". Overview of available keywords. 
  • Automated Checks: At DXPR some repositories will automatically review your Pull Request by checking your code against coding standards, or running automated black box tests using Selenium. The status and output of the checks are found on the "Checks" tab of your pull request page on GitHub. If your Pull Request fails one or more checks, you must first fix these issues so that you pass all the checks, before requesting that a human reviews your code. 
  • Discuss and review code: Teams participate in code reviews by commenting, testing, and reviewing open pull requests. Code review is at the core of an open and participatory culture. When you submit a pull request, the next thing to do is to request a review using GitHub's UI.
  • Merge: Upon clicking merge, GitHub automatically performs the equivalent of a local ‘git merge’ operation. GitHub also keeps the entire branch development history on the merged pull request. After a topic branch is merged it's deleted from the Github origin repository.
  • Deploy: Teams can choose the best release cycles or incorporate continuous integration tools and operate with the assurance that code on the deployment branch has gone through a robust workflow.


Keeping your local environment up to date

When you are working in a team that pushes code to the same repository, as is the case with the DXPR Builder repo, for example, it is likely that changes are merged into the main branches after you copied the main branch to create your topic branch. Usually, this is not a problem but if the changes are made to the same files and code blocks that you are editing, merge conflicts will arise. In order to minimize merge conflicts, it's important to stay up to date with changes to the main branches in the origin repository.

There are three things you need to do:

  • Before you make a copy of the main branch, merge all the latest changes into your local copy ( git pull origin 1.x )
  • If you work on a topic branch for more than a few days, try to pull in changes from the main branch at the beginning of every day you work on this branch
  • Clear Drupal caches on the site after pulling in new code
  • Run the database update script

Running database updates

Sometimes changes to a Drupal module will include changes to the database schema of site configuration. If this is the case, the author of the changes will have included a database update script. If your site is crashing after pulling in new changes, running the update script is a possible solution. There are two ways to do this:

  • In the browser: visit /update.php in your Drupal installation. Follow the steps in the wizard.
  • In the terminal, cd into the folder containing your Drupal files. Then run drush updb