Vlatko Vlahek

In this step by step article, you will learn why CircleCI is a great solution for multi-site deployment with Firebase and how to set it up.

Firebase multi-site deployment with CircleCI - Prototyped

A long time ago, even the simplest of build and deployment scenarios through a CI/CD pipeline were something that was out of reach for many developers, and smaller teams.

It was often the matter of the cost of having an adequate build server, or the complexity of setting everything up, even though you had great solutions like Jenkins which were free to use.

Even if you had the experience and all requirements to make it happen, it could be quite a chore to set up and maintain, making it an overhead for smaller projects, unless a dedicated team member like a DevOps engineer was available to tackle such tasks.

However, a lot of things have changed lately, as such solutions became relatively cheap and highly available. Probably all git providers now support pipeline builds, and there are a lot of dedicated hosted CI/CD solutions available out there.

This made it cheaper than ever and accessible even to developers with limited or no infrastructure knowledge. One of such solutions is CircleCI.


A journey to deploy a static website

The smallest of projects are usually the ones that most often end up being dropped to the server via ssh, RDP or FTP. And usually, these are static websites, regardless of the framework.

This doesn’t take a lot of time … when you do it once. But it gets tedious over time. But don’t settle for tedious, when it can be magical. And focus on what you want to do, which is hardly moving locally built assets around.


Firebase Hosting

There are a lot of great options for static page hosting, like Netlify, but we prefer hosting our projects with Firebase, for the following reasons:

 * great CLI
 * SSL certificate out of the box
 * almost zero config
 * great performance
 * free or very cheap for most scenarios
 * supports multi-site deployment (dev, prod, staging for example)

You can read more about it in the official docs.

Setting up the first environment on Firebase

 1. Create a Firebase account, or use your existing Google Account to log in.
 2. Create a new project
 3. Go to the Hosting tab
 4. Click on Get started button

Follow the instructions given by firebase, except firebase deploy, which is not necessary at this point.

After init inside your project, you will see the following inside your terminal:

You're about to initialize a Firebase project in this directory:

/some-path/deploy-me-softly

? Which Firebase CLI features do you want to set up for this folder? Press Space to select features, then Enter to confirm your choices. 
 ◯ Database: Deploy Firebase Realtime Database Rules
 ◯ Firestore: Deploy rules and create indexes for Firestore
 ◯ Functions: Configure and deploy Cloud Functions
❯◉ Hosting: Configure and deploy Firebase Hosting sites
 ◯ Storage: Deploy Cloud Storage security rules

Select the hosting (space), and hit enter.

You will now get a list of your projects, select the one that you will use for hosting.

You will also see an option to create a new project in the CLI. Depending on your permissions (especially if you are inside a google organization), it is possible to simplify the process by using the CLI to create a project, but this would lack some brevity on the purpose of the article itself.

After this, you will get a prompt that will require you to select a folder which will be the build folder of your app. For react apps it is the build folder by default:

=== Hosting Setup

Your public directory is the folder (relative to your project directory) that
will contain Hosting assets to be uploaded with firebase deploy. If you
have a build process for your assets, use your build's output directory.

? What do you want to use as your public directory? build

Finally, you will be prompted to select if you want the rewrite all URL’s to index.html file. If you are working with a SPA framework such as React, Angular or Vue.js the answer is generally yes.

? Configure as a single-page app (rewrite all urls to /index.html)? (y/N) y

After the initialization process, you will be redirected to a page for the first of our environments.

You will get a test domain name for it based on the project name.

Also, inside your project, you will get two new files generated:

 * .firebaserc
 * firebase.json

The .firebaserc file holds the information about the firebase projects your repository is connected to. This file will be updated automatically by the CLI when we add other sites.

The firebase.json file holds the configuration for the build artefacts that we will deploy to our environments. The default says that we want to deploy everything from the build folder and ignore everything else, including the node_modules, which is fine. We will, however, need to update it to support multi-site deployment.


Setting up the rest of the environments on Firebase

At the bottom of the current environment page, under Advanced you will see an option of adding additional sites. It should look like this:

Click on the Add another site button. You will be prompted for a name.

The decision is up to you, but if you want to have some sane naming, I suggest something in the lines of suffixing the default environment with the environment purpose you want to have. Here is a potential example:

project-name.web.app // production (the default env you got)
project-name-staging.web.app // staging
project-name-test.web.app // test

After completing the process, you will get a screen that says all three are waiting for the first release.


Applying config targets

Next, we need to connect each site we created to a firebase deployment target.

firebase target:apply hosting test project-name-test
firebase target:apply hosting staging project-name-staging
firebase target:apply hosting production project-name

Executing these commands will update the .firebaserc file inside your project with aliases for each site in your project.

Your .firebaserc file should now match this template.

We also need to modify the firebase.json file.

The default config is based on only one website. You should change it to an array of object, with a configuration for each site. Your end result should look like this.

At this moment it is not possible to reuse the same configuration for each target in the config file, even if they are exactly the same, and have no target-specific differences :(.

Detailed official documentation can be found here.


Setting up git for multi-environment deployment

To define what will be deployed to each environment, we need to set up some form of a git process around it.

There are a lot of valid workflows, depending on what your solution will be. CircleCI can support build and deployment per branch or tag basis.

The following example does revolve around using GitFlow. A more in-depth look into what GitFlow is, and how to set up and use it with rebase can be found in one of my previous articles.

The short version:

 1. install git-flow (or use integrated one if you have SourceTree, Fork etc…)
 2. run git flow init command on your repo:

git init
git flow init

3. accept defaults, optionally prefix versions with v

After initialising git-flow inside our repository, you will now have the following branches set up.

master -> production
develop -> test

What about the staging environment branch?

Considering that the staging environment sits between test and production one, and its purpose is to be a replica of production, made for testing the code which will be pushed live after we confirm that it is ok, we will tie it to the release branches inside the git-flow.

These are intended to be short-lived branches for merging stuff between develop and master, without any additional code changes. If you think about it, the logic correlates with the staging environment purpose.


Setting up CircleCI

And finally, the magic sauce to blend it all together. CircleCI is an impressive tool, with a great feature set, documentation and compared to most other solutions, very easy to set up.

But why CircleCI compared to other solutions?

A valid question. Using the pipeline directly inside your repository is most probably the easiest solution for most people.

However, there are a few things that kinda make the CircleCI stand out as a solution:

 * it’s a dedicated CI/CD solution, making it feature-packed when compared to the most integrated repository pipelines.
 * great prebuilt docker images.
 * integrates easily with your repositories upon sign up.
 * the free plan includes (2core/4gb ram containers).
 * has more credits included compared to most other systems or pipelines, which refresh weekly, making it a great starting solution even for small teams.


Let’s start

Note that the following steps use the current CircleCI interface. There is a new interface, which is quite nicer in active development but is still missing a lot of features.

 1. Create an account by signing up with GitHub or Bitbucket on https://circleci.com/
 2. After logging in, click on Add projects
 3. Click on the Set Up Project button next to your repository

On the next page, just make sure the Linux instance is selected, and continue to the next page, as we will use a custom config file to set everything up correctly.

After setting up a project, CircleCI will set up hooks on your repo, which will reference commits and pull requests during build time. The connection is two way, so you will have the information available in both CircleCI dashboard and your repository dashboard.


CircleCI config file reference

Everything tied to CircleCI deployment is done through its config file. While some people prefer tweaking stuff through an interface, from a development perspective, this is great, as it makes the project simpler and reusable, considering that you can simply copy the config from project to project.

The only thing you cannot skip is clicking the Set Up Project button next to your repository on the CircleCI interface.

A detailed reference on the config file can be found here. We will be using the 2.1 reference version.

Only a subset of the functionality is required for us to handle our case:

 * executors
 * commands
 * jobs
 * workflows

Executors are used for defining the environment in which our project will be built.

Commands are used for extracting all of the shared logic inside our steps to a single reference inside the config. They mainly help with reusability and keeping our config short and concise.

Jobs are used for defining step by step commands that we will run on our docker container used for build/deployment. Every job is a standalone step in the process.

Workflows are used to create the actual pipeline of jobs that will be run sequentially or in parallel.


Adding the config

First, create a .circleci/config.yml file inside your project.

You can find the complete configuration for this setup here.

This config includes all steps for build and deployment of our project, as well as caching steps to improve the package installation step for node_modules.

If you know how it can be improved further, drop a comment below the article. We are all here to learn, after all.


Adding the FIREBASE_TOKEN environment variable

In order for our build system to actually be able to deploy to our firebase targets, we need to give it permissions to do so. This is done by generating a ci token through the firebase CLI.

firebase login:ci

After you execute the command, you will get a secure login prompt from google to log in to your account. After a successful login, you will get a token that CircleCI can use for authentication.

The token should look like this:

1//03_VJFNodJcOSCgYIARAAGAMSNwF-L9Irbsxpbkqc2adqgHPRfqxxxxxxxxxx-xxxxxxxxxxxxxxxxx-w

In order for the whole process to be secure, we cannot simply store the token to one of our configs or hardcode it. We will add it as an environment variable inside the CircleCI dashboard.

Under the workflows section, click on the little settings cog next to your project.



On the next page, select Environment Variables and click on the Add Variable button.

Set the following:

name: FIREBASE_TOKEN
token: 1//03_VJFNodJcOSCgYIARAAGAMSNwF-L9Irbsxpbkqc2adqgHPRfqxxxxxxxxxx-xxxxxxxxxxxxxxxxx-w

The token above is the one that you got from login:ci command.

In case you already have this set up for another project, you can simply import the currently used token, which will make the process even simpler.


Every journey needs to come to an end …

Now that we have set up everything, it’s time to test how it all works together.

Push on the develop branch should deploy the test site.

Push on any release/* branch should deploy the staging site.

Push on the master branch should deploy the production site.

If everything looks and deploys ok, it is suggested that you lock down your branches and allow only merge through code-reviewed PR-s to ensure that there won’t be any accidental deployments.


Code examples

You can find the code example of how everything fits together here:

vlaja/firebase-circleci-deploymentAn example repository that features multisite deployment with Firebase and CircleCI - vlaja/firebase-circleci-deploymentGitHubvlaja

Want to get in touch? Drop us an email at hello@prototyp.digital or visit us at https://prototyp.digital. Feel free to point out if something is incorrect or you have a better way of doing stuff, we’re all here to learn :) Thanks!

DevOps

Firebase multi-site deployment with CircleCI

Find out how to create a Localized React Router with support for multiple languages that will redirect your users to correct routes. 

Multi-language routing in React - Prototyped

One of the great things around routing in React is that its ecosystem has allowed for great and very declarative routing syntax. You can define your routing as a set of components, write an object structure from which you will render the routing logic, etc.

And it’s constantly improving and getting better and better:

 * react-router v5.1 is out
 * reach router is also getting big traction, check it out.

But, what if you want to support a true multi-language routing, which will support route names in multiple languages and redirect your users to correct routes when you change languages?


Is that really a big deal?

Well, it is definitively possible to go on without such a feature and have a fully usable website. There are a lot of websites that have English-only routing, but multi-language content.

From a development perspective, the reasons for this vary:

 * A framework that doesn’t support it is used.
 * It’s a big effort to implement.
 * It’s not always easy to maintain.

However, having a multi-language route localization can give you and your end-users the following benefits:

 * multi-language SEO
 * users get the additional context of the page hierarchy in their own language

A solution written in React is relatively simple to implement and maintain, and this article will outline the packages and methods that will guide you to a solution.

The example is written with TypeScript, latest react-router-dom, and react-hooks.


Add a Router package

In case you aren’t using a router package, try react-router-dom out.

yarn add react-router-dom
yarn add @types/react-router-dom --dev

After adding a router, we should define a few routes and components that will be used on our website.

export const App: React.FC = () => (
  <BrowserRouter>
    <AppLayout>
      <Switch>
        <Route exact path={AppRoute.Home}>
          <views.Home />
        </Route>
        <Route exact path={AppRoute.Summary}>
          <views.Summary />
        </Route>
        <Route path="*">
          <views.GeneralError />
        </Route>
      </Switch>
    </AppLayout>
  </BrowserRouter>
);

In the latest react-router-dom version, component and render props were scrapped for children prop which is much more flexible. The only downside is that the v4 version was more concise and readable in most scenarios. Please note that the old way of doing things through component/render props is still available at this moment, but it will become deprecated soon.

We also added an AppLayout component which allows us to have a global header, navigation, and footer, and renders the routes inside the main tag as partial views.

There is also a fallback route here that renders the error component so our users know that they ended up on the error page in case they try to access a route that doesn’t exist.


Add an i18n package

First, we need to add a package that will allow us to internationalize things in our app. There are a lot of good examples, but one of the best packages around is react-intl.

It is a project by FormatJS (Yahoo! Inc) which has impressive support for localizing almost everything, including currencies, dates, etc.

yarn add react-intl

This package was written in Typescript so it has its own types included.


Adding a base locale

It’s always easiest to start with a language that will be the primary language for the website as a baseline. You can always add more languages easily later on.

Let’s first add an enum which will be a collection of all languages used inside our app. For start, we will only add the base language.

export enum AppLanguage {
  English = 'en',
}

The value of each enum property should match a two-letter country code ISO locale.

After adding a language, we should also add some language strings for that language, which we will use to localize our routes and other content.

Create an intl folder somewhere in the app, and a file for your base language.

const baseStrings = {
  /** Routes */
  'routes.home': '/',
  'routes.summary': '/summary',

  ...
};

export type LanguageStrings = typeof baseStrings;
export const en = baseStrings;

The exported type will be used as an equality enforcer which all other languages need to support, meaning that any localization added to baseStrings will need to be added to other files in order to enforce some safety. It also works vice-versa.

If you try to add a string to a specific language which doesn’t exist in the base strings file, you will get a compilation error. This will enforce that all of the used languages have all strings at least set, if not translated, and save you from runtime errors.

We are also exporting the baseStrings as a matching iso variable for the language at hand.

Now let’s add a matching enum (or frozen object in plain JS) which we can use to reference the routes to avoid any typos.

export enum AppRoute {
  Home = 'routes.home',
  Summary = 'routes.summary'
}


Localized Switch component

In order to simplify the process of translating the route paths, we will create a custom LocalizedSwitch component that handles this logic.

It is also possible to do this on the route component level, however, swapping out the Switch component allows you to support this with the least amount of changes, as it is easier to update the parent then every route to a LocalizedRoute variant. Changing the route component is probably a more flexible solution though.

The intended suggestion for the LocalisedSwitch component is imagined as a drop-in replacement for the normal Switch one, and it is designed to work with Route components from the react-router-dom package.

export const LocalizedSwitch: React.FC = ({ children }) => {
  /**
   * inject params and formatMessage through hooks, so we can localize the route
   */
  const { formatMessage, locale } = useIntl();

  /**
   * Apply localization to all routes
   * Also checks if all children elements are <Route /> components
   */
  return (
    <Switch>
      {React.Children.map(children, child =>
        React.isValidElement<RouteProps>(child)
          ? React.cloneElement(child, {
              ...child.props,
              path: localizeRoutePath(child.props.path)
            })
          : child
      )}
    </Switch>
  );

  /**
   *
   * @param path can be string, undefined or string array
   * @returns Localized string path or path array
   */
  function localizeRoutePath(path?: string | string[]) {
    switch (typeof path) {
      case 'undefined':
        return undefined;
      case 'object':
        return path.map(key => `/${locale}` + formatMessage({ id: key }));
      default:
        const isFallbackRoute = path === '*';
        return isFallbackRoute
          ? path
          : `/${locale}` + formatMessage({ id: path });
    }
  }
};


Wiring it all up

To wire it all together, we need to add the IntlProvider component from the react-intl package, connect it to the data we defined, and add our own LocalizedSwitch component.

export const App: React.FC = () => (
  <LocalizedRouter
    RouterComponent={BrowserRouter}
    languages={AppLanguage}
    appStrings={appStrings}
  >
    <AppLayout>
      <LocalizedSwitch>
        <Route exact path={AppRoute.Home}>
          <views.Home />
        </Route>
        <Route exact path={AppRoute.Summary}>
          <views.Summary />
        </Route>
        <Route path="*">
          <views.GeneralError />
        </Route>
      </LocalizedSwitch>
    </AppLayout>
  </LocalizedRouter>
);


Supporting multiple languages

Now that we have covered the basics of setting up the logic that allows us to internationalize our application and localize the application routes, we need to add support for other languages and add their route definitions.

For the purpose of this example, let’s add support for Deutch, French and Croatian languages, all inside the intl folder that we already have.

Disclaimer: I don’t personally speak Deutch or French, so if the translations are not perfect, I do apologize for mangling your language, but please blame Google Translate :)


Adding translations for a new language

Just add a new language file inside the intl folder:

export const de: LanguageStrings = {
  /** Routes */
  'routes.home': '/',
  'routes.summary': '/zusammenfassung',

  ...
};

If you are wondering why this was done in .ts file in this scenario, and not another format like JSON, the sole purpose is to enforce safety that comes with using TypeScript.

You can, of course, write these in JSON, JS or another preferred format in case you don’t want or need the type-safety.

For every language file you add, extend the AppLanguage enum.


Updating the router

We first need to update the router to support redirecting to other languages, reading the current language from the pathname, and setting the locale accordingly.

Expected behaviour:

/summary -> Redirect to base language
/en/summary -> English language summary page
/de/zusammenfassung -> German language summary page

We will swap out the default router component with the one that supports pathname detection and returns react-intl provider.

interface Props {
  RouterComponent: React.ComponentClass<any>;
  languages: { [k: number]: string };
  appStrings: { [prop: string]: LanguageStrings };
  defaultLanguage?: AppLanguage;
}

export const LocalizedRouter: React.FC<Props> = ({
  children,
  RouterComponent,
  appStrings,
  defaultLanguage
}) => (
  <RouterComponent>
    <Route path="/:lang([a-z]{2})">
      {({ match, location }) => {
        /**
         * Get current language
         * Set default locale to en if base path is used without a language
         */
        const params = match ? match.params : {};
        const { lang = defaultLanguage || AppLanguage.English } = params;

        /**
         * If language is not in route path, redirect to language root
         */
        const { pathname } = location;
        if (!pathname.includes(`/${lang}/`)) {
          return <Redirect to={`/${lang}/`} />;
        }

        /**
         * Return Intl provider with default language set
         */
        return (
          <IntlProvider locale={lang} messages={appStrings[lang]}>
            {children}
          </IntlProvider>
        );
      }}
    </Route>
  </RouterComponent>
);

Wrapping everything in a route, allows us to use regex to determine the language from the pathname, and use that match to inject the current language into the provider.

Also, our new router component will enforce that a language is always a part of the pathname.

The regex used in this example will only support lowercase language, but you can modify it to [a-zA-z]{2} and use String.toLowercase() method when pathname matching if you want to support uppercase routes as well.


Language switcher

We also need to add a language switcher component that will allow us to change the active language and show the currently activated language based on the pathname.

Apart from the styling, we need a helper function that checks for matching route inside the strings object for other languages if we want to support navigating to the same page in another language directly.

export const LanguageSwitcher: React.FC = () => {
  const { pathname } = useLocation();
  const { locale, messages } = useIntl();

  return (
    <ul className={css(list.container)}>
      {Object.keys(AppLanguage).map(lang => (
        <li key={lang} className={css(list.item)}>
          <NavLink
            className={css(link.primary)}
            activeClassName={css(link.active)}
            to={getMatchingRoute(AppLanguage[lang])}
          >
            {AppLanguage[lang]}
          </NavLink>
        </li>
      ))}
    </ul>
  );

  function getMatchingRoute(language: string) {
    /**
     * Get the key of the route the user is currently on
     */
    const [, route] = pathname.split(locale);
    const routeKey = Object.keys(messages).find(key => messages[key] === route);

    /**
     * Find the matching route for the new language
     */
    const matchingRoute = appStrings[language][routeKey];

    /**
     * Return localized route
     */
    return `/${language}` + matchingRoute;
  }
};


Navigation

The last thing to do is updating the Navigation component itself, to also support switching to other routes in all languages.

We simply use the formatMessage function from the react-intl hook for this purpose.

export const Navigation: React.FC = () => {
  const { formatMessage, locale } = useIntl();

  return (
    <ul className={css(list.container)}>
      {Object.keys(AppRoute).map(elem => (
        <li key={elem} className={css(list.item)}>
          <NavLink
            exact
            className={css(link.primary)}
            activeClassName={css(link.active)}
            to={localizeRouteKey(AppRoute[elem])}
          >
            {formatMessage({ id: AppRouteTitles.get(AppRoute[elem]) || '' })}
          </NavLink>
        </li>
      ))}
    </ul>
  );

In order to allow for easier route name resolution, since TS enums don’t allow for reverse mapping on string enums, you can create an ES6 map.

export const AppRouteTitles = new Map([
  [AppRoute.Home, 'home.title'],
  [AppRoute.Summary, 'summary.title']
]);


Summary

As you can see, localizing the routes of the website is not a hard task in React. It requires a few components and little thinking on the side of the project architecture, so you don’t overcomplicate things. The result is easy to understand the solution that will easily scale regardless of the language count that you might add later on.

A fully working example can be found on:

vlaja/multilanguage-routing-reactA showcase of multi-language routing with react-router dom, react-intl and hooks. - vlaja/multilanguage-routing-reactGitHubvlaja

Want to get in touch? Drop us an email at hello@prototyp.digital or visit us at https://prototyp.digital. Feel free to point out if something is incorrect or you have a better way of doing stuff, we’re all here to learn :) Thanks!

Thanks to Darjan Bogdan for his insights and comments.

Development

Multi-language routing in React

Read all about our git-flow approaches that will allow you to have a more streamlined git experience.

Avoiding messy git history - Prototyped 

If we try to name the things that have clearly defined modern software development, source control would most certainly be very high on the list, especially git which is probably the most widely used version control system today.

Days of having our code versioned in different folders locally, often prone to corruption are long gone. However, a lot of developers use git just as a means to store the source files somewhere remotely, without actually utilising some of its more advanced features that allow us to have a great, easily readable git history.

This article will cover one of the git-flow approaches, heavily based on git rebase, that will allow you to have a more streamlined git experience, especially when working inside a team. It’s a strict approach and takes a while to get used to.

The experience stems from working on bigger projects, based on the in-house practices that we have at PROTOTYP. We put a strong emphasis on code review and easy readability of all changes that happen inside our codebase.

Main goals of the approach are:

 * cleaner git history
 * fewer merge conflicts
 * enforcing code review
 * increasing branch stability

All examples in the article are done via command line, but there will be links and references on how to achieve some parts of the process in the git provider dashboards.


Initialising git flow

The first step of the journey is definitively initialising Git flow over your repository.

More thorough documentation on the matter by its original author can be found here.

In short, it’s a branching model that scaled really well for us in the past and is widely adopted.

In order to use this from the command line, you will most probably need to install git-flow. GUI solutions such as Tower or Sourcetree usually have it integrated.

You can check the installation instructions here.

Example:

// initialises git on your repository
git init
 
// initialises git flow on your git repo
git flow init



After initialising git flow on your repository, you will be asked for default branch names. We use the default values internally, only prefixing tags with letter “v”, so our versions are v1.0.0, v1.0.1 etc.

Feel free to use the versioning system for releases that has the most sense for your team and your product. However, semantic versioning or semver has been our weapon of choice for some time now, and while it could be an overkill for smaller one-off projects, it has proven great for releasing new features for SaaS products or mobile apps inside our company.

Each of the branches git flow introduces has its own place in the ecosystem, and understanding when to use each one is a must!

// New features
Feature branches? [feature/]
                   
// Tags a version and merges develop to master. 
// A short lived branch. Versions bumps are ok inside it.
Release branches? [release/]

// A branch done from master directly, for fast hotfix push
// We use bugfix/ name for a bugfix branch that is branched from  
// develop
Hotfix branches? [hotfix/]

// Need to add some client specific code ? Use a support branch
Support branches? [support/]
                   
// Tag for release branches
Version tag prefix? [v]



Remember, git is not some sort of a magic wand that makes all of your issues go away just by itself, nor does it have any sense in having multiple branches if you don’t know what to do with them in the first place.


Locking down develop and master branches

This one is maybe a tad controversial for people not used to this approach, but I would definitively note this as one of the most important steps in the process.

Protecting develop and master branches will require your team to merge code to them exclusively via merge requests, and through a code review process, which are both strongly encouraged practices.

It will also save you from a lot of potential “instability” troubles that tend to happen when people push a “small and insignificant fix that can’t break anything” directly to one of these branches. This creates a lot of frustration when things go wrong, which happens, sooner or later.

How to do it, differs from provider to provider, but here is the outline for more popular ones:

Bitbucket: https://blog.bitbucket.org/2016/12/05/protect-your-master-branch-with-merge-checks/

GitHub: https://help.github.com/articles/configuring-protected-branches/

GitLab: https://docs.gitlab.com/ee/user/project/protected_branches.html

I would suggest enabling some merge checks along, such as at least one code review and approval from another developer before merging any code to them.


Adding new code through feature branches

Considering that no code can be directly pushed to develop or master branches, it’s required that you create a new feature branch to add a new functionality to your app.

You can either do it from the command line or use integrated functionality in tools such as Sourcetree or Tower.

Source branch: develop
Naming: feature/feature-name

Example:

git checkout develop
git branch feature/my-new-feature



After you have successfully created your feature branch, feel free to push the code to it, until you are ready to get your feature reviewed as merged by another member of your team.


Merging your code

In order to merge the code via this approach, after you have finished your feature, you will first need to rebase it. This is a multi-step process.


Rebase by developer

As a developer who created a feature, you generally want to pull the latest changes from the develop branch that happened in the meantime and test whether your feature is still working.

git checkout develop
git pull
git checkout feature/your-feature-name

// This line will return a hash of commit where your branch diverged // from develop
git merge-base develop feature/your-feature-name

// {hash} is the result from the previous step
git rebase --onto develop {hash}



This will start the rebase process where changes from develop are integrated to your own feature branch, commit by commit.

Once you understand the steps that happen with rebase, there are also shorter alternatives such as:

git checkout feature/your-feature-name
git pull --rebase origin develop



You can check the complete rebase documentation here.


Why not simply use merge?

A valid point. You can, of course, merge the develop to your own feature branch and get similar results. However, there are a few key differences, why we prefer to rebase the branch over merge in this scenario.

Rebase:

 * Integrates changes commit by commit.
 * Conflicts also come in commit by commit, and it’s easy to ask your colleague what was the change to resolve the conflict more efficiently together.
 * Rebase can easily be aborted and started over, reverting all changes that you made if you are unsure if you messed up somewhere.

// After you stage files, you can continue to next commit
git rebase --continue

// Skips the current commit entirely
git rebase --skip

// Reverts all rebase changes that you did
// Returns the branch to pre-rebase state
git rebase --abort



 * You have more flexibility when rebasing as you can rename incoming commits or completely skip them, if you think they are unnecessary or superseded by your changes.
 * It doesn’t create unnecessary merge commits if you integrate changes to your feature branches often.
 * If you don’t have any conflicts, it will just pass through all commits and the process will be a breeze as it is with git merge.

Merge:



Merge glues all changes together leading to a huge amount of potentially conflicting files, and resolving the differences is often quite a chore. Also, it makes it much harder to understand who and for what reason changed a file if a conflict occurs.

However, regardless of your choice, the burden of testing the feature before creating a Pull Request is definitely on the developer, and shouldn’t be skipped.


Creating a pull request (merge request in some providers)

Create a pull request from your feature branch to develop (or branch from which you branched off) inside the interface of your git provider.

Bitbucket: https://confluence.atlassian.com/bitbucket/create-a-pull-request-to-merge-your-change-774243413.html

GitHub: https://help.github.com/en/articles/creating-a-pull-request

GitLab: https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html



Gitlab offers automatic rebase option inside their interface, a feature that I really like, and would be hyped to see it in BitBucket, for example.


Rebase by reviewer

This step is the main trick to have a readable and streamlined git history.

Unlike the developer rebase, which is used for resolving potential conflicts and testing your feature with the latest changes, this one is primarily for readability reasons, although it can also catch issues if they do happen.

We think it’s a critical step in the process because after you create a PR, you don’t know how long it will take for somebody to review and merge it.

More often than not, before this happens, there are new features merged to your development branch, which means:

 * new features might have introduced conflicts which need to be resolved
 * git history has changed from the moment you first rebased

If the reviewer does another rebase, it should improve the testing of the feature, minimise the potential of the feature not working after being merged, and provide you with a very clean and linear git history.


How does it look in practice

Here is a little screenshot from Sourcetree, showing features merged via this method, and mutual relationships between develop, master and other branches.



As you can see:

 * it’s very readable
 * release point with the tag from develop to master can be found quickly
 * you can easily see in which order your features or bug fixes were merged.
   This can help a lot if you are unsure which feature broke something else in your project. It even makes using git bisect much easier if things come to that.


Squash or no squash

The example shown here uses squash which is given as a feature by GitLab automatically, although you can squash commits locally if required, like this:

git checkout feature/my-new-feature // If you are not on it
git rebase -i HEAD~1



This would squash your whole branch to one commit. A word of advice, discuss internally if this is what you want.

From our perspective, as long as you follow the rebase flow, squash will not significantly impact the readability of your git graph, unless your features have 100+ commits.

In that scenario, maybe you bundled too much inside a single feature :).

I prefer squashing commits in a branch before doing a PR because it forces you to go for a new bugfix/ or hotfix/ branch if you messed something up. Also, regardless of whether your developers do atomic commits or huge beasts of commits, it will not matter.

However, it’s not mandatory to squash all to one single commit. If it’s a bigger feature, you can manually squash your branch to a few important commits via interactive rebase.

git checkout feature/your-feature-name
git merge-base develop feature/your-feature-name // returns {hash}
git rebase -i {hash}



You will get a screen like this:

pick be8606b Added localisation package and settings
pick 48e6aec Fixed an issue with payload not being propagated
squash 6085ce3 Added connected intl
squash 60ec657 Fixed connected intl
squash ba09d22 Modified tasks from package.json
pick 0bea497 Build android
pick 52c67b9 Updated packages
pick 21aa18c rm package lock

Simply change pick to squash to merge a commit with the commit that preceded it.

This is usually used to squash commit duplicates or commits with stupid names such as removed console.log in order to maintain a git history that is relevant and informative.


Not convinced that this is a way to go?

If you haven’t used git in this fashion it’s very understandable. At least try it out, and try to make an opinion of it after you use it for a few days or a single project.

It did allow us to improve our git usage at Prototyp, and to achieve better git readability with far fewer conflicts. And when they do happen, they are resolved quickly, allowing us to be more efficient and focus on features, and not pulling our hair out.

The process of switching to the flow on all projects was not easy and took some time. After a while though, everybody is satisfied with the results that it has brought to our team.

Here are a few final things about the process.


A few words about Git rebase

Oh boy. Not rebase, right?

For us, git rebase is one of the most powerful features that comes with git. Think of it as a swiss-tool for managing your git history.

However, opinions for this functionality are often highly opinionated and this can lead to a few misconceptions.

Here are a few:

Don’t use rebase, it’s a destructive operation !

This has some merit. Rebase rewrites git history, and can lead to disastrous results, if not used properly!

However, a lot of things with git are potentially destructive. This doesn’t mean they shouldn’t be used, just that you need to understand how and when to use them, and how to mitigate the issues if they do happen.

Be mindful of using this approach on public repositories and open-source projects where a lot of different people are pushing code, and not everybody is using the same principle. It requires the whole team to be disciplined.

Also, if several people are working on the same feature, only rebase before the pull request or if you are completely sure everybody commited their changes. Rebase does rewrite the history of your own branch, so it could lead to a lot of force pulling and pushing on the branch then, which can create a frustration of its own.

This flow only makes the git graph nicer, it doesn’t bring in any value.

I strongly disagree with this one, for multiple reasons.

First off, you can write nice code and ugly spaghetti code, but both can be functional. However, do ask yourself which is faster to understand and refactor and less prone to issues?

The same logic applies here. Added brevity is rarely a bad thing.

Also, the whole point of enforcing rebase is to minimise issues with conflicts, as they happen to be much much easier to resolve via this approach. The nice graph is only a great side effect of the whole process.

What if using rebase messes my branch and project up ?

To be honest, it’s very very hard to completely mess a project or a branch up, especially if multiple people are working on it, and have their own local versions which are ok. They can always force push the change to reset your state.

You can also mess a branch up if you use merge and commit these changes, but you haven’t resolved issues properly.

However, if you do manage to do to the unthinkable, resolving these issues is often a very easy thing to do.


Git reflog

Behold, the magic eraser pen of all the bad things that we do to our repository.

git reflog



Hitting that command will show hashes of all states in which your branch was, up to 90 days. You can simply check out or reset the branch to a state before the merge or rebase, and start over, by finding the last hash before you did any destructive operation.

Something is strange here. Sometimes I need to rebase, sometimes not. What’s the catch ?

If your branch is ahead of the tip of develop, you don’t need to do it. In the following scenario, ensure that you have pulled all changes from develop, and if you are still ahead of it, just do a Pull request.



If your branch is behind the tip of develop, you will need to rebase. Observe how the feature/other-feature is not connected to the foremost point of develop, but a point behind its tip.




Closing words

We hope that this article outlined both the process and its pros and cons, based on our experiences.

If you are looking for a new process that could bring in improvements to readability and stability of your git process, making you and your team more efficient in the process, give it a shot. It could go a long way!

If you have a similar or different workflow which works for your team, we would like to hear about it and see how it compares.

Want to get in touch? Drop us an email at hello@prototyp.digital or visit us at https://prototyp.digital. Feel free to point out if something is incorrect or you have a better way of doing stuff, we’re all here to learn :) Thanks!

Thanks to Darjan Bogdan, Sebastijan Dumančić, and Ines Komić.

AuthorVlatko Vlahek

Start a Project