A year ago my team started the journey of modernising the stack of our back office web application. The application helps assessors to manage the lifecycle of a student loan. By the time the team started thinking in modernising the stack the code base was 3 years old. The web application is part of a system of 30 microservices and it has to interact with almost all of them.
The application was originally built using jQuery and vanilla JavaScript. RequireJS was used as a module loader. At some point in the life of the application, there
was an attempt of creating individual modules using Knockout, perhaps trying to move towards the micro-frontends pattern. The test were written using Jasmine and ran with Karma. The test coverage was good as the app was built using TDD.
The team decided to do a spike to try React as a foundation for the new stack.
The goal, building a UI platform
<hr>
From modernising the stack to building a UI platform. (analogy with building the assessment platform)
Knowing your libraries inside-in
<hr>
The web app digitalizes the process of managing the lifecycle of a student loan application. The users are the assessors, responsable to take a paper application and enter all the details into the system using the application, so that the system can assess the application. As you can imagine, the UI has high amount of forms. This lead the team to evaluate using a library that abstract the complexity of managing controlled form inputs in React. We started using redux-froms without knowing very well the library and we pay the price. In our favour, the library has evolved a lot since we started using and it knows accommodates more different use cases than before.
Improving the developer experience early on
<hr>
One of the key decisions we made was to invest on improving the developers experience early on our migration journey. We migrate from Mocha and expect.js to Jest, which
includes test doubles, coverage and assertions out of the box. This helped to simplify the amount of libraries the developer had to get used to. We started by service our
integrated React app using the old gulp setup. We wanted to benefit from features like hot reloading so we quickly invest in using the web server provided by webpack.
The old codebase had JSHint as a linter. When we start using ESLint for our React code, we end up having two different linters for the three different stacks. We invest on migrating the JSHint rules to ESLint to simplify and only have one.
The same happened with Karma and Gulp.
In all the technical conversations we were having about the process of strangling the old stacks, we referred to them as legacy. As the time passed, we realized that
the modernisation of the codebase may take a while, or even stop at some point like it happened when Knockout was introduced, so we decided to invest also in the old stacks.
The first thing we did was restructuring the folder structure so that the three stacks had clear boundaries and the code was structure in a similar way.
Photo of folder structure
Up-skilling the team
<hr>
By the time we started the migration, most of our team were backend developers with a few individuals who had experience with Javascript. We knew a key aspect of the
migration success was up skilling people and sharing as much knowledge as possible. To do that, the team started organise weekly ES6 katas using the Exercism platform. A few
of us gathered at 4pm and split in pairs. We then try to complete the kata suggested for the day, after 50 minutos we gathered again and we shared and discuss all the
solutions. This helped a lot to get people up to speed to the new feature introduced in ES6 and to some degree to get people excited about the new tech.
Pair programming
We do pair programming when we work in any piece of code that will eventually be deployed in production. This helped a lot, people with a few weeks on the code base
will teach people new to React how to get started and what worked for them. They will also help them to navigate the code base and share the patterns we were
trying to follow, like the container vs presentation components pattern.
Katas
Mobbing
Creating a design system using component explorers:
<hr>
One of the key aspects of building the UI platform was to get everybody thinking about components, mostly about consistency and reusability. As we were rewriting the
different modules and creating new ones, we spotted and remove some inconsistencies in the UI. This was a joint effort between the BAs, QAs, Dev and UX people in the team.
It was not enough with having only the developers thinking and splitting UI functionality in components. We wanted the BAs and UX to be aware of the components
that already existed and how they were called, eventually creating a ubiquitos language based on components. This involved BAs referencing existing components
in the user stories and even collaborating with UX and Devs to set the names for new ones.
Developing components and isolation and discussing how to test them with the QAs allowed us to create smaller stories and built bigger pieces of the UI in
incremental steps.
Early on, we started thinking on how we could visualize our library of components that it was growing bigger and bigger with the time. We started researching if there
were any libraries that allows us to render the component directly from the source code. We found storybook and we decided to give it a try. We quickly realised the
enormous value this tool brought, not only allowing us to collaborate with QAs, BAs, UX and PO, but also in testing our components [storyshot plugin].
We started writing stories to implement individual components and mapping the different acceptance criteria scenarios to stories in the storybook instance of the
component. This helped us during desk check to evaluate if the user story was complete, and also the QA to go through the different scenarios and validate when
a component was ready.
[knobs]
Lessons learned / What we would do differently
<hr>
Conclusion
<hr>

Component libraries: A tale of a migration

I recently came across <a href="https://increment.com/development/what-its-like-to-be-a-developer-at/">a really interesting article</a> published on Increment, a digital magazine that shares ideas on how effective software teams work together. The author asks a set of questions to software developers and managers from what can be considered great product companies in the software industry about how is it to be a developer in their teams.
I don’t work or have worked for a product company, but I thought it would be interesting to answer the same set of questions so that I can see how my current experience in an agile software development team may differ from the ones in the original article.
I work as a software consultant for a company called <a href="https://www.thoughtworks.com/">ThoughtWorks</a>. As part of my job, I usually get involved in the delivery of at least a couple of software products every year, mostly by advising our clients to improve the ways they engineer those products and pairing with their engineering teams to build them.
I am currently working for a government organisation helping to evolve a loan assessment platform. Although all the answers reflect my experience as a developer in this specific project, I think they can be applied to most of the projects I have been involved with recently.
<h2>What are the most common tools that developers use?</h2>
Most of the developers use IntelliJ as IDE for JavaScript, Clojure and Java. We really like the integration with Jest to run individual tests with a simple keyboard shortcut. We use the <a href="https://cursive-ide.com/">Cursive</a> plugin to deal with Clojure’s parenthesis in a productive way. While the IDE is not enforced, having the same one with a shared setup proves more efficient for pair programming.
Git and Gitlab are used for source control, combined with <a href="https://github.com/saki/devkit">DevKit</a> to manage GitLab identities while pair programming. <a href="https://www.thoughtworks.com/mingle/">Mingle</a> is used for both project management and as a knowledge base. We use HipChat as IM and IBM Notes as email solution.
We run our development environment in a Vagrant VM running CentOS (RHEL in production) on a Windows host. Developers use <a href="https://www.gocd.org/">GoCD</a> for CI/CD, Kibana (ELK) for logging, Graphite for metrics and Icinga for monitoring and alerting.
<h2>Which languages do developers code in?</h2>
Most of our backend (micro)services are written in Clojure, with some written in Java 8. We have around 25 in total. New services are usually created in Clojure. We are able to spin up a new one quite quickly by combining automation techniques like a <a href="https://www.thoughtworks.com/radar/techniques/tailored-service-template">service template</a> for <a href="https://leiningen.org/">Leiningen</a> that includes all the common libraries and <a href="https://www.thoughtworks.com/radar/techniques/pipelines-as-code">pipeline as code</a> for GoCD.
For the back office web application we are slowly refactoring a 4 years old single page application with React/Redux using ES6 JavaScript. This frontend was built with a mix of vanilla JavaScript, jQuery and Knockout . We develop new functionality features using the new stack.
<h2>What is the development process like? (the lifecycle of a piece of committed code)</h2>
The requirements for a new product or feature usually come from Government’s policy. These requirements ultimately get split into user stories and assigned to a cross-functional team. The developers help the business analysts (BAs) and quality analysts (QAs) in the team to review the story from a technical perspective. When <a href="https://www.agilealliance.org/glossary/three-amigos/#q=~(filters~(postType~(~&#x27;page~&#x27;post~&#x27;aa_book~&#x27;aa_event_session~&#x27;aa_experience_report~&#x27;aa_glossary~&#x27;aa_research_paper~&#x27;aa_video)~tags~(~&#x27;three*20amigos))~searchTerm~&#x27;~sort~false~sortDirection~&#x27;asc~page~1)">the three amigos</a> think that the story is ready to be played, it is moved to the next stage in our physical (and digital) Kanban wall, “ready for dev”.
After that, a pair of developers start working on the story. We swap pairs every two or three days in order to share context as much as possible. The pair that started the story may not be the same that completes it, although one of the people usually sticks with the story till completion. When the story is ready, it is desk-checked by the three amigos again. The QA then starts analysing the quality of the functionality built through exploratory testing and at the same time assessing test coverage and cross-functional requirements.
When the QA finishes and the product owner (PO) is available, the story is showcased to the PO to get it signed off, authorising it to be released. If the PO is happy, the story is moved into ready for release, usually being released the next day.
<h2>What is code review like?</h2>
We don’t have many code reviews. We work on the principle that all production code should be delivered by doing pair programming. Developers pair with their peers and always push changes to master (<a href="https://paulhammant.com/2013/04/05/what-is-trunk-based-development/">trunk-based development</a>). We do use additional branches to explore technical solutions, like assessing a new library or a new design.
Sometimes, the tech lead or feature leads review other people code after they pushed to master to ensure the technical direction is kept and new changes do not break or impact the design of a service or the system as a whole.
<h2>How is testing done, and what kind of tests are run?</h2>
Developers write unit (we follow TDD), integration, service/functional level tests. They also help the QAs to write automated end to end tests that exercise the whole system, some of them through the UI. We also have <a href="https://storybook.js.org/testing/structural-testing/">snapshot tests</a> for our reusable React components (thanks to Storybook.js and Jest) and some contract tests between microservices and external services using <a href="https://docs.pact.io/">Pact</a>.
In addition to the local development environment, all these tests run in the build and deployment pipelines of our continuous delivery pipeline. The QAs also perform some exploratory testing in a staging environment, mostly through the UI and sometimes through Swagger, the tool we use to document our REST APIs.
<h2>How is code deployed?</h2>
We push to master all the time, which means that each individual commit must be able to be deployed in production without breaking functionality or must be under a <a href="https://martinfowler.com/articles/feature-toggles.html">feature flag</a>. Each commit has a story number and the names of the pair that authored it, that is how we track each piece of work.
As an example, every time a commit of the assessment service is pushed to master, the service build pipeline gets triggered. A GoCD agent builds the service and runs the automated test suite, among other things like linters. If the process completes successfully, a new version of the assessment service is automatically deployed to the first staging environment where end to end tests exercise the system.
Once a user story involving this service is completed and the QA and the PO are happy with the functionality to be deployed, the new version of the assessment service is scheduled to be released in the next release window given by the change management (CM) department of the company. This department has to authorise all the releases we do and they use the story numbers to track and understand the changes being deployed to production.
Given this constrain, quite common in organisations like this, we usually deploy to production only once a day. In most cases this deployment involves not only one, but several services.
When the deployment is authorised, the pair organising promotes the new version of the assessment service and the other services included in the deployment into a pre-production environment and conducts some smoke tests. The new functionality is then deployed during the release window agreed with CM. We then check our monitoring and alerting systems to verify if any of the new changes have broken the system.
<h2>What is an average day-in-the-life of someone on one of the development teams?</h2>
The development team working on the assessment platform is split into smaller teams following <a href="https://medium.com/project-management-learnings/spotify-squad-framework-part-i-8f74bcfcd761">Spotify’s squads model</a>. Each squad is cross-functional, formed by Devs, QAs, BAs and a a developer that acts as technical leader. Each squad owns a piece of the functionality of the platform.
The day starts with each squad daily standup, where people walk the Kanban wall talking about the progress made in each story, what they are planing to do that day and surfacing any blocker that may get in the way.
Most of the time, a developer is pairing with a peer in delivering theuser story functionality. Other times is pairing with a BA analysing the technical details of a piece of work, or with the Tech Lead, helping him or her set the technical direction of a feature, evolving the architecture of the system, etc.
The squad holds showcase sessions every two weeks to share what they have done with the other squads. Developers, QAs and BAs are usually the ones showcasing the progress made. Another ceremony, the team retrospective, is done every two weeks. Developers take an active role on this session reflecting on how the team can work more effectively. The squads also organise technical sessions called “code time” or “tech congress” where developers share technical solutions and discuss technical topics.
We tried to follow the <a href="https://www.thoughtworks.com/insights/blog/there-no-such-thing-devops-team">“you build it, you run it”</a> principle, which implies that some times, as a developer, you will be pairing with someone from other squad to support the production system during working hours. This requires working with the customer support teams in investigating production issues and trying to solve them. An additional developer from the client is on call outside working hours.
<h2>What makes this project a special place to be a developer?</h2>
I will quote one of the answers from the original article.
<blockquote>
There’s a real feeling that while writing code can be a solitary act, making software isn’t. People are really kind and generous with their knowledge, and overwhelmingly willing to help.
</blockquote>
In my team writing code is a collaborative act, thanks to practicing pair programming, one of the core practices we follow at ThoughtWorks. You can have a bad day or lose motivation, but your pair will always try to help you to forget about it and carry on doing great work.
Moreover, I personally like the technical challenges I have faced in this project. Building and evolving a platform based on a microservices architecture on top of very rigid virtualised infrastructure, flaky networks (self-managed data centres..) and in the context of a “risk-adverse” organisation is always a challenge.
I hope you found my answers useful or at least enjoyable to read. I encourage you to do the same exercise and share with us how it is like to be a developer in your current project. And please, if you have any recommendations on how my team can improve their development experience, share them in the comments.
You can find other tools that we use checking <a href="https://stackshare.io/portovep/loan-assessment-platform">this stack</a> on Stackshare.
PS: If you would be interesting to join me in this project, please leave me a PM :).

Pablo Porto

My blog