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 [https://jenkins.io/] 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
[http://circleci.com/].

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
[https://www.netlify.com/], 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
[https://firebase.google.com/docs/hosting].

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
[https://gist.github.com/vlaja/3821436df0bf37d95094bf6e2295d1a5].

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 [https://gist.github.com/vlaja/3b179c1bd6ea3781fe461ebc2ee0d90d].

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
[https://firebase.google.com/docs/hosting/multisites].

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
[https://medium.com/prototyped/avoiding-the-messy-git-history-508c9066e63b].

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
[https://circleci.com/docs/2.0/configuration-reference/]. 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
[https://gist.github.com/vlaja/7a024b75c9412ad32eb40c6b5d2e04a3].

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-deploymentvlaja
GitHub [https://github.com/vlaja/firebase-circleci-deployment]
--------------------------------------------------------------------------------

Want to get in touch? Drop us an email at hello@prototyp.digital or visit us at 
https://prototyp.digital [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 [https://reacttraining.com/blog/react-router-v5-1/]
 * reach [https://reach.tech/router] 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
[https://www.npmjs.com/package/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>
);

An example of a react-router-dom v5.1 structureIn 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 [https://github.com/formatjs/react-intl].

It is a project by FormatJS [https://formatjs.io/] (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;

Base application strings fileThe 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'
}

A dictionary of all app routes and their pathsLocalized 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 });
    }
  }
};

Localized Switch component that will handle translating the app routesWiring it
all up
To wire it all together, we need to add the IntlProvider component from the 
react-intl [https://github.com/formatjs/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>
);

All wired up to read routes from translation filesSupporting 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',

  ...
};

intl/de.tsIf 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>
);

Localized router componentWrapping 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;
  }
};

The language switcher logicNavigation
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>
  );

Localized navigationIn 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']
]);

Route title mapSummary
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-reactvlaja
GitHub [https://github.com/vlaja/multilanguage-routing-react]
--------------------------------------------------------------------------------

Want to get in touch? Drop us an email at hello@prototyp.digital or visit us at 
https://prototyp.digital [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 [https://prototyp.digital/]. 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 [https://nvie.com/posts/a-successful-git-branching-model/].

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
[https://danielkummer.github.io/git-flow-cheatsheet/].

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
[https://semver.org/] 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 [https://www.sourcetreeapp.com/] or Tower
[https://www.git-tower.com/mac].

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
[https://git-scm.com/docs/git-rebase].

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 chaos

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
   [https://git-scm.com/docs/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
[https://medium.com/u/2cb071b44a1e?source=post_page-----508c9066e63b----------------------]
, 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 [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