Git merge requests

The Gitlab Merge Request feature is used to request code changes as part of our change management process.

How to make a Merge Request

Pull from the DEV branch of the git repository and create your own branch to develop your feature/site (direct “push” access is not permitted). We recommend the following naming convention your branch: <project-name>-<release>.

  1. Once your feature is complete, push your feature branch to git and create a Merge Request in Gitlab
    • IMPORTANT - Use the following release type terms within the title of your Gitlab merge requests. For example: “Company - Service name - Alpha 1”
  2. Feedback or defects will be communicated as Gitlab issues.
  3. Once the branch has been accepted we will merge your submission into the DEV branch.
  4. Once a “Release Candidate” (read about release management) is deployed the DEV branch, eServices will need approval from the project team to proceed to deploy any work to UAT.
  5. Approval to proceed to UAT can be documented using Gitlab comments on the merge request.
  6. Once features/site has been approved in UAT by eServices, those commits containing the relevant features can be pulled into production.

Why we have merge requests?

  • communicate between parties
  • verification of work
  • support our change management process
  • accountability
  • traceability
  • provide history
  • documentation
  • repeatability of deployment

Goal of merge request documentation

Explain what is being delivered. Explain how it works.

Explain how to install/enable it.

Identify any know issues, pitfalls or bugs.

Explain how to verify that it's working correctly.

Any special notes, considerations, etc.

They should be like release notes. Imagine that the merge request is the only communication that goes with your code delivery. Will it and the code be clear enough to recipients that they will be able to understand, review, deploy, test and evaluate the work?

A merge request should contain sufficient detail that no further communication is required in order to code review the change, deploy it and then test it.

Audience of merge request documentation

Consider the different audiences that will use this information:

  • eServices: to understand what is in the package; to get an idea of what to expect when this is deployed
  • Code reviewer: to understand the context of this work; to clarify constraints, rationalle and other considerations around the implementation
  • Deployers: how to enable this thing; how to know it's working
  • Service owner: what features to review, test or focus on; understand the scope of features being delivered



The merge request title should be in the format: {Company name} - {project} - {release}


  • CompanyA - Open data CSV harvest - alpha 2
  • CompanyB - HSS - RC 2
  • CompanyC - ENV Permit hunt authorization - RC 3


Nearly always the dev branch.


This work includes

  • {feature 1}
  • {feature 2}
  • {...}
{feature 1 title}

{Feature 1 writeup}

{feature 2 title}

{Feature 2 writeup}


Known issues

{List of outstanding items, incomplete aspects or other pitfalls}.


{Pertinent details about this work}

Deployment instructions

  1. {steps to enable these changes}
  2. {preferably using command line}

{simple instructions to verify that deployment worked}


Title: Devers - Pinball - RC1

This work includes

  • Foos page
  • Dinglehoper reduction
Foos page

This release includes a new module, FooBar, which collects all the Foos on a single page. This is done using the Foo services, which requires an API key. {...}

Dinglehoper reduction

By varying the fizzlebender, the site now uses substantially fewer dinglehopers. This applies to all page except /user which is totally infested.

The new Foobar should be visible at /all/you/foos.

Known issues

This release include only a partial implementation of the fizbat system.


After discussing with the client, we agree to limit the number of Foos displayed to factors of 42. This was done to please the pixies. If it needs to be changed, check the constant name FOOS_PER_PAGE near line 934.

Deployment instructions

  1. Roll out the code changes
  2. Enable the FooBar module drush en foobar
  3. Add the API key in the admin page /admin/foobar

Next: Release types and activities →

Last update:
Jun 3, 2019