Frontend Development Guidelines

This document describes various guidelines to ensure consistency and quality across GitLab's frontend team.

Overview

GitLab is built on top of Ruby on Rails using Haml with Hamlit. Be wary of the limitations that come with using Hamlit. We also use SCSS and plain JavaScript with modern ECMAScript standards supported through Babel and ES module support through webpack.

We also utilize webpack to handle the bundling, minification, and compression of our assets.

Working with our frontend assets requires Node (v4.3 or greater) and Yarn (v0.17 or greater). You can find information on how to install these on our installation guide.

jQuery is used throughout the application's JavaScript, with Vue.js for particularly advanced, dynamic elements.

Browser Support

For our currently-supported browsers, see our requirements.

Development Process

When you are assigned an issue please follow the next steps:

Divide a big feature into small Merge Requests

Big Merge Request are painful to review. In order to make this process easier we must break a big feature into smaller ones and create a Merge Request for each step.
First step is to create a branch from master, let's call it new-feature. This branch will be the recipient of all the smaller Merge Requests. Only this one will be merged to master.
Don't do any work on this one, let's keep it synced with master.
Create a new branch from new-feature, let's call it new-feature-step-1. We advise you to clearly identify which step the branch represents.
Do the first part of the modifications in this branch. The target branch of this Merge Request should be new-feature.
Once new-feature-step-1 gets merged into new-feature we can continue our work. Create a new branch from new-feature, let's call it new-feature-step-2 and repeat the process done before.

master
└─ new-feature
   ├─ new-feature-step-1
   ├─ new-feature-step-2
   └─ new-feature-step-3

Tips

Make sure new-feature branch is always synced with master: merge master frequently.
Do the same for the feature branch you have opened. This can be accomplished by merging master into new-feature and new-feature into new-feature-step-*
Avoid rewriting history.

Share your work early

Before writing code guarantee your vision of the architecture is aligned with GitLab's architecture.
Add a diagram to the issue and ask a Frontend Architecture about it.

Don't take more than one week between starting work on a feature and sharing a Merge Request with a reviewer or a maintainer.

Vue features

Follow the steps in Vue.js Best Practices
Follow the style guide.
Only a handful of people are allowed to merge Vue related features. Reach out to one of Vue experts early in this process.