<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Robin Eisenberg on Medium]]></title>
        <description><![CDATA[Stories by Robin Eisenberg on Medium]]></description>
        <link>https://medium.com/@eisenbergrobin?source=rss-a3712cb9e2f7------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*A37DMMFJ4PSMcNrTS31pkg@2x.png</url>
            <title>Stories by Robin Eisenberg on Medium</title>
            <link>https://medium.com/@eisenbergrobin?source=rss-a3712cb9e2f7------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 07:17:02 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@eisenbergrobin/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Lessons learned in 2 years with a JavaScript/React Monorepo]]></title>
            <link>https://medium.com/botify-labs/lessons-learned-in-2-years-with-a-javascript-react-monorepo-526e2154d5f1?source=rss-a3712cb9e2f7------2</link>
            <guid isPermaLink="false">https://medium.com/p/526e2154d5f1</guid>
            <category><![CDATA[engineering-mangement]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[monorepo]]></category>
            <category><![CDATA[react]]></category>
            <dc:creator><![CDATA[Robin Eisenberg]]></dc:creator>
            <pubDate>Thu, 07 Jun 2018 21:36:01 GMT</pubDate>
            <atom:updated>2018-06-07T21:36:01.315Z</atom:updated>
            <content:encoded><![CDATA[<p>Things we learned from 2 years of maintaining a JavaScript/React Monorepo</p><p><em>Two years ago, our team moved all of our JavaScript applications into a single monorepo. We’ve had time to let the dust settle on our decision, and to hit a few walls along the way — we thought we’d share them with the world.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/990/1*KhABj3BXgT6IrhKz3RXkbg.png" /></figure><h3>Why a monorepo ?</h3><p>We have a lot of different SPAs here at Botify. Our product is a suite of different components and tools that have different uses for different customers. Our JavaScript team of around 10 Engineers maintains:</p><ul><li>4 major SPAs</li><li>3 more minor web applications</li><li>An internally-hosted Storybook</li><li>JS SDKs</li><li>a Chrome Extension</li><li>PDF generators (node bundles)</li><li>Embedded browser bundles</li></ul><p>This is a lot of code, in a lot of different places. Moreover, some of these packages have a lot in common (the SPAs), and some are wildly different in function and in the artefacts produced (Chrome Extension, Embeds, SDKs).</p><p>Originally these projects were all separate git repos, with their own lint, build scripts, CI/CD, codestyle, and sometimes even technologies. This caused a lot of problems:</p><ul><li>Codebase is diverse, some legacy is hard to maintain or left behind</li><li>Commonization of UI/CSS is difficult (building views for multiple apps)</li><li>Code uniformity is worse</li><li>Lint/Build/Deploy/Release scripts have to be managed separately</li><li>CI/CD has to be managed separately</li><li>PRs have to be managed in different repos</li><li>Dependencies between packages require multiple PRs, with dependency changes</li><li>Team is slower at scaling in size</li></ul><p>Two years ago we decided to bring them all into a single monorepo, to try and solve these issues. Here’s what we’ve learned along the way.</p><h3>How we monorepo ?</h3><p>Our JS frontend monorepo’s top-level directory looks like this:</p><pre>├── .nvmrc</pre><pre>├── .prettierrc</pre><pre>├── .sass-lint.yml</pre><pre>├── .travis.yml</pre><pre>├── .editorconfig</pre><pre>├── .eslintignore</pre><pre>├── .eslintrc.js</pre><pre>├── .babelrc</pre><pre>├── CONVENTIONS.md</pre><pre>├── README.md</pre><pre>├── apps/</pre><pre>│ ├── common-style/</pre><pre>│ ├── common-js/</pre><pre>│ ├── chrome-extension/</pre><pre>│ ├── botify-embeddable/</pre><pre>│ ├── sdk-js/</pre><pre>│ ├── app1/</pre><pre>│ ├── app2/</pre><pre>│ ├── …</pre><pre>├── config/</pre><pre>│ ├── apps.js</pre><pre>│ ├── …</pre><pre>├── package.json</pre><pre>├── postcss.config.js</pre><pre>├── script/</pre><pre>│ ├── …</pre><pre>├── webpack.config.js</pre><pre>└── yarn.lock</pre><p>Each of the directories in ./apps has its own package.json and dependencies, and each app produces a separate artefact versioned and released on its own. Some apps, like common-style and common-js, are just commonized code that is imported inside some of the applications, they do not produce any artefacts.</p><h3>Sharing a common core</h3><p>The biggest gain we’ve had from switching to a monorepo has been our increase in commonization, and uniformization of our code. As much as possible we try to reuse code and have common rules that are respected throughout the codebase. This allows every engineer to be able to work on any part of the codebase and feel at home.</p><p>Here are the things we’ve made common for our whole codebase:</p><h4>Common rules</h4><p>We have a set of rules and a code style, and we enforce it through CI (a PR fails CI build for style issues). This allows us to leave style discussions out of reviews, and augment readability of the code. As stated below, we have regular discussions about these rules and make them evolve when needed.</p><ul><li>ESLint // Prettier // PostCSS</li></ul><p>At the root of the monorepo are configuration files for eslint, postcss, and prettier with our rules for code style. These apply to every line of code in the repo and allow us to keep a consistent coding style between different applications. This helps developers feel at home on any part of the codebase.</p><p>On a side note, prettier and eslint autofix have really helped us obtain a no-fuss working environment, both in terms of code style when reviewing, and ease of use with IDE integrations. The fact that all code is formatted and checked against Botify guidelines every time one of us hits ‘Save’ in our IDE is a big time-saver for the team.</p><ul><li>Babel</li></ul><p>Our transpiler rule file is also at the top-level, and apart from some very special apps, all of Botify’s JavaScript code follows the same ECMA spec. We mostly use language features that are LTS, but we have a few babel plugins for proposals in late stages. Our babelrc allows us to make sure all of Botify’s code is written in the same JavaScript, and minimizes errors in production due to developers not having the language tools they need on older stacks. Again, like our styleguide it also allows our code to be more uniform.</p><h4>Common scripts</h4><p>Our top-level ./scripts folder looks like this:</p><pre>├── script/</pre><pre>│ ├── build</pre><pre>│ ├── deploy</pre><pre>│ ├── install</pre><pre>│ ├── lint</pre><pre>│ ├── release</pre><pre>│ ├── start</pre><pre>│ ├── stats</pre><pre>│ ├── test</pre><pre>│ └── utils</pre><p>All of these scripts pretty much do what their names say, and they work for all applications in the repo. That means that linting, building, testing, deploying, and releasing an application all goes through the same scripts. It also enables anyone in the Botify Product team to make a new release, and deploy it, quickly, simply, and regardless of the application being released.</p><p>Bonus (because I know you are curious and wondering): ‘stats’ is a commonized script to run a build with module statistics (webpack — stats) to display a treemap of the weight of the built bundle. It allows us to study our dependency tree, and perform dependency optimization to reduce bundle size quickly.</p><ul><li>Webpack</li></ul><p>Our build script is completely common, and all apps are built through the same script, using webpack. However since the artifacts we build are so different (browser bundles, node bundles, chrome extension, etc..) we’ve built a way to commonize as much as possible about our webpack builds.</p><p>We have a top-level webpack.config.js that contains the most common version of our configuration, and it will pull the application’s own webpack.config.js if there is one to make modifications to the build rules before passing the configuration to webpack:</p><p>Top-level webpack.config.js:</p><pre><strong>module</strong>.<strong>exports</strong> = (app, { _ = [] } = {}) =&gt; {</pre><pre><strong>  const </strong>appWebpackConfig = <strong>require</strong>(`./apps/${app}/webpack.config`);</pre><pre><strong>  const </strong>baseConfig = {</pre><pre>    …</pre><pre>  };</pre><pre><strong>  return </strong>appWebpackConfig(baseConfig, { isProduction });</pre><pre>};</pre><p>Which calls <em>appWebpackConfig</em>, a function exported by the child application’s <em>webpack.config.js</em> that can modify rules in the configuration according to its needs.</p><p>This allows us to run `<em>yarn build &lt;app&gt;</em>` from the top-level and have a build of the app, using common build configurations while customizing the build for the needs of the app.</p><p>All builds, of course, are produced in the application’s <em>./dist</em> directory.</p><ul><li>CI/CD/Workflow integration scripts</li></ul><p>Linting, building, testing, and deploying is done on CI. Again, we’ve created top-level scripts for each of these actions to be performed for each application.</p><p>When running on CI, we’ve built a simple function to determine which application has been changed and which application needs to be tested on CI. When a CI build starts, Travis performs a git diff to find which apps have modified files in the branch. It then checks these modified files against dependencies declared between applications (eg: all application depend on common-js and are rebuilt if the common package is modified) to build a dependency tree. The tree is then flattened and CI only tests applications that need to be tested in the PR. This saves us a lot of build time on Travis.</p><p>We use Travis Build Stages to run this in a coherent and modularized manner. We are looking into experimenting with Build Matrices to allow for a fully blown-up CI architecture into a single container for each application.</p><h3># What we’ve learned</h3><h4>Create a common code package, use it as much as possible</h4><p>DRY is a principle we hold to heart Botify. We as a team very strongly believe that the best code is no code at all, and reusing as much as possible between our apps eliminates extra code surface that we have to maintain.</p><p>We created two ‘apps’ in the monorepo, common-style, and common-js, that are repositories for all the common code used in other applications. They contain anything from utility functions for string manipulation, to common components and views used between applications.</p><p>Important gotcha: we use webpack aliases to alias our common code packages, so that imports to the common packages are also the same everywhere (this makes refactors much easier). In all our applications, code from the common bundle can be imported via “import { …} from ‘common-js/…’”. When refactoring code in common-js, we can easily find and replace imports because they are never relative. This rule is declared in the common webpack configuration and automatically added to all applications.</p><ul><li>Common utilities</li></ul><p>As much as possible, we want to reuse small functions and utilities between our different applications. Our common-js/utils folder looks like this:</p><pre>utils</pre><pre>├── async.js</pre><pre>├── chart.js</pre><pre>├── common.js</pre><pre>├── constants.js</pre><pre>├── datamodel.js</pre><pre>├── dimension.js</pre><pre>├── dom.js</pre><pre>├── filter.js</pre><pre>├── filterBlock.js</pre><pre>├── layout.js</pre><pre>├── moment.js</pre><pre>├── predicates.js</pre><pre>├── propTypes.js</pre><pre>├── query.js</pre><pre>├── react.js</pre><pre>├── reporting.js</pre><pre>├── routing.js</pre><pre>├── searchableTree.js</pre><pre>├── segments.js</pre><pre>└── trackUser.js</pre><p>A big set of utilities, very various in what they do, some purely technical (eg: dom, react), and some more functional/business (eg: filter, datamodel, segments). They are used all over Botify applications in the repo and they help us be able to make evolutions to large systems quickly.</p><p>We also have some utilities that are just wrappers around implementations that differ in different applications. For example, we have a legacy application using BackboneJS, and everything we’ve written in the past two years uses React-Router, so we have a utility to abstract routing away into these two specific implementations. Our routing utility can route, no matter which application we’re in, and the stack details are left unknown to the consumer of the module — because they’re not important, all they want to do is route.</p><ul><li>Common views</li></ul><p>Our UI team internally has built a UI Kit, a set of components common to our UIs that can be used when composing views.</p><p>Our common package contains React components that are to be reused throughout our applications. This is very important and allows for a more unified design between each component of the repo.</p><p>For example, the <em>&lt;Button /&gt;</em> we use in our Botify Extension is the exact same component as the one used in our login page.</p><p>This allows us to update core UI in one place, and have the changes apply to all of our apps.</p><p>As a bonus, it’s allowed us to build a Storybook app to collaborate with the UI team on evolutions to the components. Each common component has a demo in the Botify Storybook, and the UI team has access to an internally-hosted version. This gives us a quick feedback loop when working on the core components that make the Botify UI.</p><ul><li>Common redux code</li></ul><p>We use Redux and Redux-Sage extensively, and we’ve managed to commonize a lot of business logic, data-wrangling, and charting code so we can reuse it in different applications.</p><p>A lot of core concepts of any group of products within a suite are common: Users, Groups, Authentication, Authorization, etc. This logic is usually handled in Redux, and we have reducers and a store structure that is reused between different applications.</p><p>Our stores for each app is usually structured in the same way, and reducers work across the board the same way for one application or another.</p><p>We also use Redux-Saga for the initialization of all of our applications. Initializing a Botify application usually means fetching a lot of metadata about the Botify project being requested, and the different components it has (Crawl, Logs, Keywords, Analytics, etc…). One of our products’ strength is Botify’s ability to cross data between multiple sources (crawls, log data, analytics, etc…). Our common sagas allow us to fetch data and wrangle it in the same way regardless of the product, and therefore allows us to create vizualizations that cross these datasets more easily.</p><p>Our common sagas fill our stores in a standardized way, and our common reducers can easily work on any store under the standard.</p><h4>Always bundle the react version from the app</h4><p>Nobody has said this better than @danabramov (<a href="http://(https//medium.com/@dan_abramov/two-weird-tricks-that-fix-react-7cf9bbdef375)">here</a>):</p><blockquote>Two Reacts Won’t Be Friends</blockquote><p>A common problem in React monorepos is inadvertently loading two copies of React. Your common code has a `<em>react</em>` dependency, your libraries have `<em>react</em>` dependencies, and your application has a `react` dependency, so it’s easy for Webpack, if it is not well configured, to load the wrong copy of `<em>react</em>`.</p><p>We solved them using our common Webpack configuration, which forces the bundler to look for React in the application’s dependencies first and foremost.</p><h4>Unify your react versions</h4><p>Unifying your React version between packages is important for a simple reason: components that are reused from application to application, which reside in the common bundle, need to work the same way in all applications. It hasn’t happened in awhile as React has made less and less breaking changes, but quirks between React versions can still happen, especially with a &lt;16/&gt;16 mix with React Fiber. Unifying our React versions across the board eliminates these kinds of headaches before getting them.</p><p>On a side note: we’ve used Facebook’s codemods in the past to update legacy code, and it’s worked very well for us so far.</p><h4>Do not use the factory pattern</h4><p>Anyone working with this kind of code split will be tempted to use the Factory pattern — we were! And we’ve found that it was a huge mistake.</p><p>Here’s an example that illustrates why:</p><p>You have a formatting, function. It formats fields according to their type (integer, float, string, etc…). For 99% of our fields, this code will be common, so it resides in the common package:</p><pre><strong>const</strong> formatField = (field) =&gt; ...</pre><p>However, in some applications, we are going to want to override this formatter for the special needs of the application. Let’s say we augment this behaviour with our own formatter in an application:</p><pre><strong>import</strong> { formatField } <strong>from</strong> ‘common’;</pre><pre><strong>const</strong> applicationFormatField = (field) =&gt; {</pre><pre>   <strong>if</strong> (…) { <strong>return</strong> applicationSpecificFormat; }</pre><pre>   <strong>return</strong> formatField(field);</pre><pre>}</pre><p>Now any consumer that wants to format needs to import the correct formatter from its own app.</p><p>Say we make a formatting component afterwards:</p><pre><strong>const</strong> formattingComponent = (value) =&gt; &lt;div&gt; {formatFunction(value)}&lt;/div&gt;</pre><p>Now if we want to make this component common, we end up with:</p><pre><strong>const</strong> formattingComponent = (formatFunction) =&gt; (value) =&gt; <br>  &lt;div&gt; {formatFunction(value)}&lt;/div&gt;</pre><p>From our experience, this pattern scales very badly when there are many things to inject. With time, we ended up needing to provide a lot of different app-specific modules (formatters, fetchers, cachers, transformers) for common components. Factories quickly become very impractical in this case.</p><p>The solution here is to use some form of dependency injection, like React’s ‘context’ API (I would not recommend, for other reasons), or Classes (difficult to use with components since there is no multiple inheritance in JavaScript).</p><p>We opted for a simple homebrewed dependency injector:</p><pre><strong>import </strong>{ mapValues } <strong>from </strong>&#39;lodash&#39;;<br><br>// Plain object that will store all provided dependency<br><strong>const </strong>_dependencies = {};</pre><pre><strong>export function </strong>provide(dependencyName, dependency) {<br>  _dependencies[dependencyName] = dependency;<br>}<br><br><strong>export function </strong>inject(dependencies) {<br>  <strong>return </strong>(wrapped) =&gt; {<br>    <strong>return </strong>(...args) =&gt; {<br>      <strong>const </strong>resolvedDependencies = mapValues(dependencies, (dependency) =&gt; {<br>        <strong>return </strong>_dependencies[dependency];<br>      });<br>      <strong>return </strong>wrapped(resolvedDependencies)(...args);<br>    };<br>  };<br>}</pre><p>At some point, an application does:</p><pre>provide(&#39;formatField&#39;, formatField);</pre><p>And consuming components can just request it from the dependency injector:</p><pre><strong>const</strong> getFormatField = inject({ format: &#39;formatField&#39; })(<br>  ({ format }) =&gt; format)<br>);<br><strong>const</strong> formattingComponent = (value) =&gt; <br>  &lt;div&gt; {getFormatField()(value)} &lt;/div&gt;</pre><p>This removes the need to change the surface API of the common component when making these components common, and it helps make refactors simpler.</p><p>This short piece of code has its limits and we use it sparingly, but it allows us to inject application-specific dependencies into any function (and therefore any React component).</p><h4>Have frequent discussions about amending conventions, and do it</h4><p>As mentioned in our <a href="https://medium.com/botify-labs/no-fuss-no-ego-code-reviews-done-right-de69b5cf76e3">previous post</a>, we at Botify think it is very important to have frequent discussions about our rules and our styleguide, and frequently amend them. We hold monthly meetings where any developer can submit these kind of amendments and we can discuss them.</p><p>In the past two years this method has made sure we’ve kept up with changes in the JavaScript language, and today we are using the latest LTS JavaScript features in our codebase.</p><p>There are still a lot of things that we’ve discussed internally but not had a chance to implement or try out, including:</p><ul><li>Using yarn workspaces to segment our application workspaces</li><li>Using lerna or some other tooling for js monorepos</li><li>Using Travis build matrices to build applications concurrently on CI</li></ul><p>How are you running your repo? There might be limits to our approach that we have not run into yet. Feel free to chime in in the comments!</p><p>Interested in joining us? We’re <a href="https://www.botify.com/careers/">hiring</a>! Don’ t hesitate to shoot me an email if there are no open positions that match your skills, we are always on the lookout for passionate people.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=526e2154d5f1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/botify-labs/lessons-learned-in-2-years-with-a-javascript-react-monorepo-526e2154d5f1">Lessons learned in 2 years with a JavaScript/React Monorepo</a> was originally published in <a href="https://medium.com/botify-labs">Botify Labs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[No fuss, no ego: Code Reviews done right]]></title>
            <link>https://medium.com/botify-labs/no-fuss-no-ego-code-reviews-done-right-de69b5cf76e3?source=rss-a3712cb9e2f7------2</link>
            <guid isPermaLink="false">https://medium.com/p/de69b5cf76e3</guid>
            <category><![CDATA[team-management]]></category>
            <category><![CDATA[agile-methodology]]></category>
            <category><![CDATA[teamwork]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[code-review]]></category>
            <dc:creator><![CDATA[Robin Eisenberg]]></dc:creator>
            <pubDate>Wed, 11 Apr 2018 20:43:51 GMT</pubDate>
            <atom:updated>2018-04-13T12:19:58.787Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/500/1*QZcSJKl09TNCMFbq7UHksQ.png" /><figcaption>Our goal is to achieve 0 WTFs/min</figcaption></figure><p>Here at Botify we’ve been reviewing code since the beginning of our journey, and we’ve learned a lot along the way. After four years of changes, we believe we’ve landed on a code-review method that works (for us at least), and we thought we’d share and discuss it with the world.</p><p><em>Disclaimer: we do not claim that this is the ‘right’ way to review code as a team. This is a method that works for us, for our team size, and our stacks and tools. Mileage may vary.</em></p><h3>TLDR;</h3><p>For effective, fast, and efficient reviews amongst an engineering team:</p><ul><li>Leave your ego at the door</li><li>Have a team mindset</li><li>Align the team on why and how reviews are performed</li><li>Set review rules and follow them</li><li>Discuss changes to the rules regularly</li></ul><h3><strong>Why?</strong></h3><p>Before delving into how we review code here at Botify, I want to talk about why we review code. It is paramount in an engineering team that the whole team be aligned on why they review code, and the effect it has on the team and on the codebase.</p><h4><strong>Betterment of the product</strong></h4><blockquote>Reviews help us in our quest to provide the best possible product for our customers.</blockquote><p>As a team, all Botifyers are extremely customer-centric: it is one of our core values and permeates throughout the whole company, from the Engineer performing a code-review to the CSM onboarding a new customer.</p><p>In that mindset, the first reason why we review code is for the betterment of the Botify product. A good code-review is like a time-machine: it allows our team to catch bugs before they even arise, and therefore before the customer sees them. We review code first and foremost because it makes the product better, and in turn because it makes the customer’s experience on Botify better.</p><h4><strong>Betterment of the code</strong></h4><blockquote>Reviews make our code stronger</blockquote><p>Some review comments aren’t about function — they are purely about code, and code architecture. Reviews allow something that we are lucky to have in our profession: a second set of eyes on our work.</p><p>In that sense, we review code so that we can catch bugs, discrepancies, edge-cases, DRY cases, and architectural mistakes <strong>before</strong> they get to production. A “Review KO”, in a sense, is a headache from the future that we’ve stopped before it even happens. Reviews allow everyone to have a say in our codebase, since everyone will have to maintain it. We review because it makes our production code stronger, less prone to mistakes, and more in line with what the whole team wants to do.</p><h4><strong>Betterment of the team</strong></h4><blockquote>Reviews power-up our team</blockquote><p>A very important aspect of reviews is that they allow for the diffusion of knowledge within the team. When maintaining a large codebase, reviews allow everyone to have a look at every part of the codebase, and therefore to learn about parts of the code that they are not working on. The more experienced developers get to share their knowledge just by doing their job, and in return they also learn new techniques from the more junior developers always trying the latest tech. Everyone benefits from this sharing of knowledge — reviews help our team get better at what we do.</p><h3><strong>How?</strong></h3><p>There are a few prerequisites required for a well-oiled reviewing machine. They are:</p><h4>A Team mindset</h4><p>This is probably the most important part of why our reviews work, so follow closely. They are three simple rules that all engineers in the team must always keep at heart, and they are at the core of our review method:</p><ol><li>Egoless — Leave your ego at the door</li><li>Goodwill — We are all in the same boat</li><li>We review code to make the product, the code, and team better</li></ol><p>These rules are what allows us to have <strong>reviews that focus on the right problems.</strong></p><p>“<em>Leave your ego at the door</em>” simply means that we review code, not people. It means that code reviews will always be about the code, and never about the people writing it. It requires developers to put their ego aside when reviewing and being reviewed. It hinges on our engineer’s individual belief that their team members are good at what they do, <strong>always</strong>, and that a mistake (or near-sightedness in a solution) can happen to anyone, from the most experienced Rockstar developer to the Junior engineer just starting out. It rests on the belief that code is <strong>not</strong> an extension of the person writing it. This is the most important part of our method.</p><p>“<em>We are all in the same boat</em>” simply means that we ask engineers to have goodwill towards their fellow team members, and goodwill towards the product. That means that it is their job, when submitting a PR to:</p><ul><li>Limit the risk of the code in terms of the product</li><li>Present their PR in a readable way to their coworkers</li></ul><p>We consider that reviewees must always present a clean, commented, and well committed PR — failure to do so is abrasive for the team and the team members who are going to review the PR. In that sense, we ask that developers review their own PRs before submitting them, rewriting the git history if necessary, so that they can present something readable and understandable by the whole team.</p><p>And finally, as described above, we as a team know why we are reviewing code, and trust that a review comment is made in the hope of bettering either the product, the codebase, or the team.</p><h4>A Review Convention</h4><p>We believe that it is important to have a guideline to be followed by engineers in the team when reviewing code. Here’s ours for an example:</p><blockquote>The Review Convention:</blockquote><blockquote><strong>Code reviews are about code, not people.</strong></blockquote><blockquote>Review comments don’t always have to be about betterment of the reviewed code, they can propose improvements in code style, comments, documentation, or tests.</blockquote><blockquote>As a <strong>reviewee</strong>:</blockquote><blockquote>- When submitting a PR, <strong>check that your PR is valid, does what it should do, passes tests (CI), and does not contain any code that is not related to your PR</strong></blockquote><blockquote>- Never take a PR comment <strong>personally</strong> (PR reviews are about <strong>code</strong>, not <strong>people</strong>).</blockquote><blockquote><strong>- All constructive comments are valid</strong>, regardless of the rank of the developer making them. Address all comments, either in the code or in the PR comments.</blockquote><blockquote>- If you don’t agree with one of the comments made to your code, discuss it <strong>constructively</strong> with your peers. Involve a third party if the discussion does not lead to a solution.</blockquote><blockquote>- When addressing review comments, create <strong>one commit per fix</strong>, not a big commit that ‘Fixes all review comments’.</blockquote><blockquote>As a <strong>reviewer</strong>:</blockquote><blockquote>- Comments should always be <strong>constructive</strong>: never put a comment that does not indicate the problem and how to fix it. If the comment requires discussion, leave it open for discussion.</blockquote><blockquote>- Comments should always be <strong>about the code</strong> — <strong>no personal vendettas</strong>.</blockquote><blockquote>- As a general rule a <strong>question</strong> <strong>should not be a KO reason</strong> — if you have comments, they don’t need to be questions but affirmations.</blockquote><blockquote><strong>- Never ask a question that can be answered by simply reading the code</strong>: this just shows you have not read/understood the code in question</blockquote><blockquote>- Sometimes problems in the code are not functional. <strong>Valid reasons for KO</strong>: Code does not work, or does not work as intended (edge cases); Code does not follow the code style of the repo; Code patterns do not follow the rest of the repo; Code does not have enough comments (things are too hard to understand); Code is missing tests; Code is missing documentation (if needed); PR format is not valid; Branch format is not valid; Code does not pass Lint; Code does not pass Tests.</blockquote><p>This document is read by all newcomers and all rules described here are at the core of how we review each other’s code.</p><h4>Clear statuses for all PRs</h4><p>It’s important for everyone in the team to be able to know in what state a PR is at any time. POs and the QA team need to know when a task is started, in review, reviewed, and ready to be tested, so they can prepare their workflows around the development team. We simply use Github tags to manage everything, and all PRs follow a convention on setting or changing their status:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*v_aLhoVwpoOrOYkX." /></figure><p>Each tag on a PR means something to someone: we speak of ‘hot’ or ‘cold’ states for the person looking at the PRs, representing whether they should do something (review, fix reviews, or merge). Everything has its place, and everyone knows when they intervene on a PR. To ease the use of such a system, we scripted a lot of the transitions on these tags to trigger JIRA, CI/CD, or QA actions.</p><h4>Script everything</h4><p>Just like for linting, in order to reduce noise and overhead work for engineers, we’ve scripted a lot of interactions between reviews and our task-tracking tools. Review actions in our Github trigger issue transitions in JIRA, and JIRA comments or transitions trigger Github review status changes.</p><p>When a PR is created, our Github bot links the PR to the JIRA issue, in JIRA and in Github:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*mfaxa7jyWeYmu8EA." /></figure><p>When a PR changes states, the JIRA issue is transitioned accordingly by the bot:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*V5H4lu3ICMwU_jY6." /></figure><p>We even have the bot automatically deploy a test environment after the CI build, for automated testing.</p><p>We believe that anything that can be automated in a team’s process should be automated, and we’ve spent time creating tools that make our lives easier. As a side note: the tool we’ve built to handle our automated transitions uses @serverless, via AWS APIGateway and Lambda, and was an opportunity for one of our engineers to do a little R&amp;D on the serverless ecosystem, and share it with the team (in a Chapter meeting) — so it’s time we’ve spent but the ROI is clear.</p><h4>Linters and a styleguide tested on CI</h4><p>At Botify we try as much as possible to reduce <strong>noise</strong> in PR Reviews, so we can make them more efficient. Part of that is solving as many discussions as possible by tests and CI, so that in our review, we can focus on the product and how it works more than just the code and how it looks. As a team, we agreed upon a styleguide, created rulesets on our linters to automatically lint the code according to our styleguide, and we run a lint check on CI when running tests. A PR that fails to follow the Botify styleguide therefore does not pass tests, and style discussions are entirely skipped. Engineers waste less time reviewing code style, and more time reviewing code function.</p><h4>Regular discussions about the stack and how we do things</h4><p>Once we’ve set up a styleguide and linter checks, we make sure to have regular discussions about it. The languages we use are evolving, and we are learning from our experience, therefore it’s important to have a regular discussion about what needs changing in the styleguide. More than just linting, it’s paramount to have regular discussions about “How we do things” as a team.</p><p>Here at Botify, we organize what we call “Chapter Meetings” every month, where developers working on a shared codebases get together to have a discussion. We share experiences — mistakes, discoveries, research, or conclusions — from the past month and discuss to ensure that every engineer in the team is aligned with the common mindset. This allows us to have <strong>less surprises when reviewing</strong>, as engineers are already familiar with the approach used in the PR.</p><h4>Peer Reviews when necessary</h4><p>Sometimes preparation, automatisation, and goodwill is not enough. Some PRs are just too big, too architectural, or too complex to be reviewed alone. In this case we have side-by-side peer reviews with the developer who made the PR. We try to make each PR readable individually as much as possible, but know to do peer reviews when necessary.</p><p>For big architectural changes that concern everyone, we organize ‘<em>Review Parties</em>’ where we get the whole team together in a meeting room, and the developer who made the PR presents their code to the team in a live-review on a big screen.</p><p><strong>It’s important to have strong processes in place for the 99% of PRs that need it, and to have the agility to bypass them when need arises for the 1%.</strong></p><h3>Final Thoughts</h3><p>All-in-all, we believe that most of what is required for good reviews has been said up to here. Once you’ve set up a common mindset that is pure, and provided the tools and structure as described above, reviews become more focused, with less friction, and more pertinent.</p><h4>And the results are staggering! Based on statistics over the last 30 days:</h4><ul><li><strong>84% of PRs get reviewed within 24hrs</strong></li><li><strong>46% of PRs get KOed — these are bugs or headaches we caught before production!</strong></li><li><strong>29% of PRs get reviewed by more than one developer</strong></li><li><strong>11% of PRs need several passes for reviews (multiple KOs)</strong></li><li><strong>31% of PRs are presented as to be reviewed commit-by-commit</strong></li></ul><p>How are you running your code reviews? Our method works for us and our team, but it does not apply to everyone. What’s different with your team ? Feel free to chime in in the comments!</p><p>Interested in joining us? We’re <a href="https://www.botify.com/careers/">hiring</a>! Don’ t hesitate to shoot me an email if there are no open positions that match your skills, we are always on the lookout for passionate people.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=de69b5cf76e3" width="1" height="1" alt=""><hr><p><a href="https://medium.com/botify-labs/no-fuss-no-ego-code-reviews-done-right-de69b5cf76e3">No fuss, no ego: Code Reviews done right</a> was originally published in <a href="https://medium.com/botify-labs">Botify Labs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>