Workflow Archives - Building Productive https://productive.io/engineering/category/workflow/ Just another Productive Sites site Mon, 22 May 2023 09:51:52 +0000 en-US hourly 1 How to Keep Your Project From Stagnating https://productive.io/engineering/how-to-keep-your-project-from-stagnating/ https://productive.io/engineering/how-to-keep-your-project-from-stagnating/#respond Mon, 22 May 2023 07:40:47 +0000 https://productive.io/engineering/?p=747 The post How to Keep Your Project From Stagnating appeared first on Building Productive.

]]>

How to Keep Your Project From Stagnating

Davor Tvorić

Frontend Engineer at Productive. Excited about anything related to computer science. I spend most of my personal time reading and playing video games.

May 22, 2023

I’m always pushing myself to look at the big picture of a project I’ve been working on.

You can easily get tunnel vision when working on a larger project, so it’s imperative that you constantly remind yourself to put everything in perspective.

This most commonly refers to a project’s business logic or domain, but an equally important aspect revolves around the technical implementation of a project. This can easily be overlooked so I’ll try to explain why you should think about it a bit more.

A Fresh New Start

Any time I start working on an unknown project, I always get the feeling that there’s too much bloat. I’m eager to do things my way. Sometimes my way really is better. Most of the time it’s the constrictions of the project that caused something simple to become complicated. This isn’t related only to code, but to third-party library dependencies, the architecture of a project, and so much more.

The worst thing you can hear in this particular scenario is “That’s how we’ve always done it” or “Here be dragons, so just leave it”.

Alright, maybe it’s not the worst thing, but it certainly doesn’t get your hopes up.

This might mean that you’re just stuck adding to a legacy that will just become more and more complex to get a hold of. Now, add a team of people doing the same and you’ll see how quickly the situation can get out of control.

A Glimmer of Hope

Luckily, this is not the case at Productive. I’m so glad to have finally found people with a similar mindset and a similar drive to improve what needs improvement. The whole idea is that each team member can and should contribute in any way they can. And there are plenty of options when it comes to contributing: 

I’m sure you can think of some more examples as well. Some are easier, some are more complex, but all of them are important. As I’ve said, this shouldn’t be something you do entirely on your own. You’re required to talk to your team and come up with the best possible way to improve an existing issue. It might not be the very best solution right off the bat, but it’s a step in the right direction. After you get the ball rolling, other people might be motivated to have a crack at something!

The idea that you have to be very experienced to do these kinds of things sometimes held me back from doing as much as I could have. I always thought that someone could do this better than me, someone with more experience or knowledge. That might be true, but if you have an idea and the time, it could be a great opportunity to learn and become better. Even if you’re new to the company, you’re most probably the best person to update the onboarding documentation because you can easily find out which step wasn’t clear enough! 

Organizing the Desire to Improve

  • Having a verbal agreement doesn’t cut it most of the time
  • Try to write down everything notable related to a certain initiative
  • Recognize the problems in a specific area and write down what exactly needs to be fixed
  • Having an end-goal will help everyone stay on the same page
  • Assign a responsible person (or people) for the initiative
  • That person doesn’t necessarily have to do the work (although they can), but they must keep track of both completed and remaining work
  • This would be equivalent to a project manager, but for a specific initiative
  • If possible, rotate the responsible people on an initiative
  • It will be an opportunity to learn more about the system and spark some new ideas
  • Let your stakeholders be aware of the initiatives and plan alongside them
  • Obviously, it’s not possible to spend your whole week on an initiative, but a shorter amount of consistent work should be enough to make meaningful steps forward
  • We try to invest from 15% to 20% each week, if possible
  • Organize your time and priorities regarding your daily work and initiatives

Add these points in with having all team members involved, as well as good communication, and you’ve got yourself a pretty sweet deal! The functionalities and the bug fixes will still be pumped out, but the overall developer experience and codebase quality will surely go up instead of down. This can also help people get a grip on a complex issue that might otherwise be left untouched.

A Couple of Speed Bumps Along The Way

Even though our experience has definitely been positive, not everything was perfect from the start. Some initiatives didn’t pick up as much as we expected, even though their general idea was important.

After we talked to our team members, we realized that the scope of certain initiatives was too broad. The general idea was good, but people didn’t know where and how to start.

To alleviate this, we split the problematic initiatives and narrowed them down as much as we could. That’s why it’s very important to talk to your teammates and get actual feedback, especially if you notice something unusual.

If you’re stuck on thinking what could be improved in your project, here are some of our initiatives that we came up with:

  • Release/deployment initiative
  • Improve the whole process ranging from generating builds to automating and posting a change list to Slack
  • Bug tracking initiative
  • Increase the number of resolved bugs and decrease the response time on each bug
  • Refactoring initiative
  • Components and parts of the system need to be simplified if possible
  • Improve the developer experience
  • Monitoring initiative
  • Improve the alerting and monitoring of our projects
  • Package manager initiative
  • Automate the process for keeping track and updating packages on all of our projects
  • Modernizing initiative
  • Keep track of inefficient practices and improve them with modern solutions
  • Schema migration initiative
  • Research and lower the risk of database migrations
  • Onboarding initiative
  • Ease the onboarding process and improve complex steps
  • UI framework initiative
  • Connect the design systems and create a library of simple components that are currently scattered

I’m convinced that things would go a lot slower if we stuck to doing improvements on the fly and without responsible people. Therefore, I’m really glad this took off because it’s really inspiring to see people make an effort in domains that are not as focused as they should be.

Once everyone started recognizing the benefits of an initiative, all sorts of ideas started coming out. It’s amazing how you get used to something so quickly, but a little push sets off a chain reaction that has you questioning why you didn’t think of something earlier.

I hope this helps you out and encourages you to try out something similar for yourselves!

Davor Tvorić

Frontend Engineer at Productive. Excited about anything related to computer science. I spend most of my personal time reading and playing video games.
More From This Author

Related articles

Related jobs

The post How to Keep Your Project From Stagnating appeared first on Building Productive.

]]>
https://productive.io/engineering/how-to-keep-your-project-from-stagnating/feed/ 0
The Productive Way of Working https://productive.io/engineering/the-productive-way-of-working/ https://productive.io/engineering/the-productive-way-of-working/#respond Wed, 01 Mar 2023 13:27:37 +0000 https://productive.io/engineering/?p=543 Instead of me telling you how great our company is or how great our product is, I’ll tell you a story of how I adapted to the Productive way of working.

The post The Productive Way of Working appeared first on Building Productive.

]]>

The Productive Way of Working

Filip Ivanko

Backend Engineer at Productive. Forever a technology student. Professional at starting anew.

March 1, 2023

Today more than ever, companies have a ton of options concerning workplace organization.

The trend of moving away from traditional, on-site work to various remote options was greatly accelerated in 2020. But we’re still (always) asking ourselves: what’s the best workplace model? What will yield the most productivity and the most employee satisfaction?

Several models have emerged. All of these models have their strengths and weaknesses, both in the productivity aspect and in the employee satisfaction aspect. Different employees have different needs for their work model. If meeting these needs means better productivity, why not let the employees choose?

At Productive we get to “pick our poison”: on-site work, remote work, work from home and hybrid work—along with a very flexible scheme for determining your work hours. In our teams we managed to solve this discrepancy using various technologies, organizational practices, and of course—our Productive app

For most employees, the ability to choose your own work models is a great thing. But guess what? You can’t choose your colleague’s work mode or schedule. Technology is what you need to bridge the gap. Good thing for us: we build the technology that bridges that gap

Instead of me telling you how great our company is or how great our product is, I’ll tell you a story of how I adapted to the Productive way of working.

Collaboration in Projects, Tasks and Docs

I prefer working on-site. The personal interaction and lack of distractions that you get from going to the office is something that works best for me. When I made the switch from my last job to Productive it was a profound change. The biggest difference was the asynchronous mode of communication, and work. I still go to the office every day, but I cannot rely on finding everyone there. Working at separate locations and at different times demands a different type of communication. 

We manage most things regarding daily tasks through Projects and Tasks in the Productive app. Tasks contain the work that needs to be done along with everybody’s input and discussions. So popping into to someone’s office and discussing a certain topic is replaced by discussions in the task comments of the app. Some of the social interaction may be lost, but the feedback is permanently there—so there’s no chance of forgetting something. 

Tasks are an integral part of every day work. If you need advice, tag someone in a comment on a task and they will be notified. If you need someone to do something minor on the task, assign them a todo on a task. If your part of the task is done, assign a task to the person that will take over. You “own” the task until your part is done and the work done is described in the comments. So a software bug task will typically change several owners, from the Customer support department to Development, and finally QA.

Collaboration is further enhanced by our own Productive Docs, the part of the Productive app for collaborating on documents. Docs enable us to have all the documentation and information readily available, reviewable and up to date. The process we use for writing Docs is in many ways similar to the process we use for writing code. Someone writes and someone reviews. The writing and reviewing is done elegantly with Docs in Productive, using tasks to facilitate the editing process.

Asynchronous Synchronisation

Doing things this way means working on certain things can be more intermittent. The Productive app has your back there as well: you can track the time you spent working on each task and tracking what part of a task was done on which day. It means that you are able to work on an assignment, stop and work on something else while you are waiting for feedback, and resume once you get it. This is rarely the case in traditional, on-site work. If you talk to five people about a something and try to work on that thing a week later, you will probably forget a lot of the details, but if the discussion is written down—nothing is lost. 

Vertical Product Teams

Our team organization follows a matrix structure so each developer belongs to a technology team and a product team. The technology teams are set up based on which technology a developer uses. In our case these teams encompass frontend technologies and backend technologies. 

Along with the classic frontend-backend division developers are also grouped into product teams. These are teams comprising of both frontend and backend developers along with designers that all work on a specific part of the product. 

Good synchronisation along these two axes is crucial and weekly meetings for each of them facilitate this. So a developer will typically attend two weekly meetings, in one meeting we sync with all the people working on the same product to coordinate our efforts, and in the other we discuss the technical challenges and improvements.

Integrations and Useful Tools

Of course, Slack provides an extra layer of details, since it’s a tool made for real-time communication. When you need to communicate about something to a larger number of people or to someone directly about something more urgent, Slack is the way to go. 

Another layer of communication for Productive developers are GitHub comments and reviews—primarily for code-related communication. So the communication imperative is: whatever you’re doing, whatever you’re thinking, write it down somewhere because you probably aren’t going to catch the people who need to know that thing you talked about by the water cooler or in the cafeteria at lunch. 

When I first came to Productive, I must say I found it challenging to replace all the information gained through informal, in-person interactions with written ones. It’s quite hard to use charm or humour to defuse situations involving professional disagreements or criticism when the medium of communication is the GitHub comments section. 

Social Interaction Is Still Important

Not all people express themselves in the same way, and they also won’t all interpret the same communication in the same manner. The better the employees know each other, the less chance there is for miscommunication. 

At Productive, this is solved by regular team social activities covered by the “Fun & games” budget. So chitchat by the water cooler is replaced by chit chat over hamburgers and beer. In my opinion, these gatherings are not only fun, in this type of workplace model they are absolutely necessary. 

So, what is it like to be an in-office worker in this kind of environment? For me, it’s like remote work, but from the office. You get most of the benefits of office work—like separated working and living space, plus interactions with coworkers that come to the office. The main difference is that most of the communication regarding work must be done online. 

Sometimes the colleagues you’re working with are going to be at the office, but all information must still be shared online, so that all the people who need or want to have information get it as they would if they were at the office. 

It’s Easier To Be Productive With Productive

With great power comes great responsibility, so if everyone wants the flexibility to work on their own terms, we all have make the effort to work together. If you’re looking for a tool that could help you and your coworkers manage time and tasks you should check out Productive, an end-to-end agency management tool.

Filip Ivanko

Backend Engineer at Productive. Forever a technology student. Professional at starting anew.
More From This Author

Related articles

Related jobs

The post The Productive Way of Working appeared first on Building Productive.

]]>
https://productive.io/engineering/the-productive-way-of-working/feed/ 0
Are You Documenting Your Project Enough? https://productive.io/engineering/are-you-documenting-your-project-enough/ https://productive.io/engineering/are-you-documenting-your-project-enough/#respond Thu, 02 Feb 2023 12:20:46 +0000 https://productive.io/engineering/?p=508 Writing documentation is important but tedious. I don’t know how you feel about it, but when I do it, it hurts my brain.

The post Are You Documenting Your Project Enough? appeared first on Building Productive.

]]>

Are You Documenting Your Project Enough?

Davor Tvorić

Frontend Engineer at Productive. Excited about anything related to computer science. I spend most of my personal time reading and playing video games.

February 2, 2023

Writing documentation is important but tedious. We’re all probably aware that we have to write documentation for the products we develop. I don’t know how you feel about it, but when I do it, it hurts my brain.

It’s not even that difficult (most of the time), but the whole process around it is what makes it so dull. Personally, I enjoy writing, but even I have to force myself to write a couple of sentences about what I’ve done. But you gotta do it, baby.

I’ll be explaining the techniques we incorporated in our workflow to improve the whole documentation situation. If you’re struggling with this, I’m sure you’ll be able to take away some ideas from this post.

The Problem With Documentation

I won’t spend too much time explaining why documentation is important and who benefits from it because I’m sure you already know that. I’ll mention some problems that I’ve run into when dealing with documentation.

When I first started working at Productive, there was already a fair share of documentation. A lot of things were documented, from setting up your workstation to details about using a specific component. I was excited about being brought up to speed with everything, but I started running into cases and features that were either not detailed enough or not documented at all. Even though I was optimistic at first, this didn’t really surprise me since it’s a huge codebase with a lot in it. This just meant that I’d have to ping other colleagues and figure some stuff out on my own.

Fast forward a couple of months, it was my time to write documentation. Up until this point, I was very excited about documenting everything I’ve done. But when it was time to write something, I had this nagging feeling in my head. I knew that it had to be done, but now I had to think about how and why something was done in a particular way, how detailed the explanations should be, where to actually write the documentation, and a whole lot more. It’s even worse when it’s a system that you don’t completely understand and you start asking yourself if you’re the best choice for writing this piece of documentation.

So many problems—and I haven’t even started writing any documentation yet.

A Helping Hand

Now, this sounds a bit more dramatic, but all of these thoughts passed through my mind at some point. We quickly brainstormed a couple of ideas to tackle the problems mentioned above. If we had some sort of a process and a frictionless way of writing documentation, everyone would have a lot more brain power to actually write documentation as opposed to worrying about issues related to writing documentation.

Here are the things we agreed upon:

  • Everyone should write documentation
  • It doesn’t have to be perfect
  • Document everything that caused you to dig deeper or reach out to a colleague
  • Continuous documentation
  • Delete outdated documentation
  • Documentation Driven Development

Now, let me take you through each.

Everyone Should Write Documentation

This is something I had to get used to, as you can probably tell from my experience when I just joined Productive. It doesn’t mean that you should only document new features you’ve worked on, but even the old ones that you might not completely understand. You can always request a review from someone who has more experience to double check what you wrote. Even if it isn’t entirely correct, it’ll probably be much easier for the other person to advise what to focus on as opposed to a blank slate. An important thing to mention is that we also encourage asking more experienced colleagues to write a part of the documentation if it’s something complex or too difficult to piece together.

It Doesn’t Have To Be Perfect

This ties in nicely with my previous point. Since documentation is something you iterate over constantly, it’s okay to just write some information down without paying too much attention to grammar, structure and completeness. It’s important to create a process that is as frictionless as possible in order to increase the engagement of everyone in the team. You can always improve the wording a bit later and other people can give feedback really quickly, even if they don’t fully understand the feature you’re working on.

Document Everything That Caused You To Dig Deeper or Reach Out to a Colleague

Besides documenting new features and maintaining old ones, make sure that incomplete documentation gets the love it deserves. More often than not we run into something that exists in the documentation, but our specific case isn’t covered. This could also mean we’re approaching an issue in the wrong way, but still, we have to take initiative and document it. Chances are that someone else will have the same issue and if you take time to document it, they will have to spend significantly less time handling the issue.

Documenting something this way could be considered a “bottom-up” approach. Instead of documenting the whole process/feature, you just write down the specific case. Doing it this way could be a little bit “easier” because you don’t have to know every little detail about the whole feature. Just remember, whether it’s an onboarding topic or something highly technical, it should be a candidate for documentation to avoid confusion!

Continuous Documentation

This one is, subjectively, the hardest. The whole process is simple: just like with continuous integration and continuous deployment, we have to maintain our documentation at all times. If a process/feature is worthy of documentation, a good time to write something about it is just after the process/feature is stable. A better time to write something about it would be even before you start coding, if that’s possible for the feature you’re writing about. Writing down everything while the information is still fresh will help you flesh out the whole story, not just parts of it. If you’re writing about it a couple of weeks later, you’re bound to forget some of the nuances that bugged you during development. Doing it later on could possibly be the beginning of incomplete documentation, so it makes sense to nip it in the bud.

Delete Outdated Documentation

Having outdated documentation is worse than having no documentation. This will just raise questions when something doesn’t behave as it says in the documentation. If you find yourself in a similar situation, make sure you delete it so it doesn’t confuse more people.

Documentation Driven Development

As mentioned, another approach we’ve considered is writing documentation before you start coding. This is something we’ve found helpful, gathering your thoughts around a feature makes developing it easier. This is also a great way to include non-technical people in the process and iron out some discrepancies even before a line of code has been written.

What I’m Trying To Say

Having documentation is really important for everyone, no matter the seniority level or the amount of time you’ve been working on a project. Having said that, it’s not easy to encourage yourself or others to just write documentation.

You can make this a lot easier by reducing the amount of friction when writing documentation. Start by defining a time and place for writing documentation and involving your whole team. 

While you’re researching tools that could be helpful, don’t forget to check out Productive and our Docs! It could be helpful to add the extra step in your workflow, like including it in the estimates and requiring changes in the documentation when submitting a pull request. You can treat this just as you would treat writing tests since they complement each other. This will, most certainly, increase the time required to finish a task, but it’s just as important as the other parts of a feature.

This should make a good foundation for everyone to contribute and iterate over each other’s work. Hopefully, these small steps snowball into a more manageable project and make everyone’s life easier.

Davor Tvorić

Frontend Engineer at Productive. Excited about anything related to computer science. I spend most of my personal time reading and playing video games.
More From This Author

Related articles

Related jobs

The post Are You Documenting Your Project Enough? appeared first on Building Productive.

]]>
https://productive.io/engineering/are-you-documenting-your-project-enough/feed/ 0
So, You’ve Started Tracking Errors. Now What? https://productive.io/engineering/so-youve-started-tracking-errors-now-what/ https://productive.io/engineering/so-youve-started-tracking-errors-now-what/#respond Wed, 14 Dec 2022 13:10:06 +0000 https://productive.io/engineering/?p=460 Let me start off with a little exercise. Just sit back, close your eyes and let me know if this sounds familiar. Well, maybe you shouldn’t close your eyes.

The post So, You’ve Started Tracking Errors. Now What? appeared first on Building Productive.

]]>

So, You’ve Started Tracking Errors. Now What?

Davor Tvorić

Frontend Engineer at Productive. Excited about anything related to computer science. I spend most of my personal time reading and playing video games.

December 14, 2022

Let me start off with a little exercise. Just sit back, close your eyes and let me know if this sounds familiar. Well, maybe you shouldn’t close your eyes.

Anyway, you’ve been working on a project for some time now. Some bugs are reported to you now and then, but you feel something’s off. 

You suddenly remember that it would be a good idea to set up some kind of an error tracking system. There are a few choices, like Sentry, Bugsnag, Rollbar and some more. After choosing wisely, you install everything necessary and, lo and behold, some errors are starting to show up! 

And now comes the critical part. You promise yourself that you’ll check the error reports periodically and fix them as they come in. If that sounds familiar, chances are that these error reports aren’t getting fixed as diligently as you’d expect.

Now What?

What I just described is the current situation at Productive. Bugs are getting fixed, but the ones that don’t “stand out” are kind of getting overlooked. Another issue is that the error reports are in Bugsnag, so they’re not in your face when you start working on your tasks for the day. As a consequence, our product managers aren’t always aware of the error reports so they can’t plan accordingly.

As part of our team’s internal initiative, for some time now, we’ve been aware that it just isn’t enough to set up an error tracking system. A process around it must exist. Just like with tasks, someone has to be responsible, the level of priority must be evaluated, and the error reports must be considered part of the workload. And now, with more people in our team, we can finally make things right.

In this post, I’ll show you an overview of all the things we’re trying to improve to really get a grip on bugs and errors. 

Since we’re currently working on this whole process, some things might change or some new points might get added, but the general idea will still stand.

Defining the Pain Points

First of all, I’ll let you in on a small glimpse into the current state of our Bugsnag:

I’m sure this might come as a surprise to some of you, but when you have a lot of users doing all sorts of things in your app, things are bound to go wrong. 

Even though this will be improved, as it is—this still gives a lot of information on how to organize a seemingly unrelated bunch of errors.

I’ve briefly mentioned which issues bothered us the most. There were a couple of issues on top of that, which we found out about after running a quick poll between our team members:

  • The reported bugs are just posted in a Slack channel, without any categorization and with little filtering
  • Sometimes the reported bugs are too vague 
  • Lots of irrelevant bugs are reported, so there’s a lot of noise
  • No one is assigned to the bugs
  • The bugs from the latest release aren’t tagged in any significant way
  • The code in the bug reports is minified
  • Sometimes the bugs are really hard to reproduce and the lack of the additional state of the app at the time makes it even harder to reproduce them
  • We’re not sure exactly how many bugs have been dealt with

Now would be a good point to mention that these issues built up over time. Depending on the size of your project/team, the architecture or workflow, some issues might be more important than others. The key here is to find out what is really slowing down your team, but feel free to use this list as an inspiration.

Plan Accordingly

After we’ve identified and written down the actual issues, the team collaboration kicked in and we got a lot of ideas on how to improve our situation.

The first step was to create a plan of attack. Taking all the issues into consideration, we came up with a list of potential solutions that might help us out. Since this was some sort of a brainstorming session, everyone was encouraged to leave their opinions and suggestions. 

Doing it this way, we were sure that we covered all the pain points that bothered the very people that were working on the bug reports.

Needless to say, you can’t do all of these things at once. Some priorities came up during the brainstorming session and here’s what we came up with:

Upload the source maps to Bugsnag

Create a solution to sync the bugs from Bugsnag with tasks in Productive

By using webhooks or Bugsnag API, fetch the relevant data from Bugsnag and send it to Productive

Find a way to categorize, prioritize and assign the bugs to the correct team members

Define who the correct team members are, so they can resolve or delegate the bug

Categorize the bug according to the route where the error occurred (until we accompany the bugs with relevant metadata)

Notify the assigned team members of the reported bug

Set the priority based on the number of occurrences

Send additional metadata for each bug to ease the reproduction process

Filter out irrelevant bugs (like one-offs and similar)

Find a way to automate deleting old or stale bug reports

Decide on a threshold for the notifications

This relates to the second point

Ease the process of generating a report for fixed/reported bugs

I agree, it’s a big list. There’s a lot to do, but it’s not necessary to finish them all before we can reap the rewards. The most obvious thing was to upload the source maps since it’s not that difficult to do, but will tremendously help out when resolving bugs.

Some of the points are a bit touch-and-go. We’ll set something up, but some parts might change after we get a feel of how everything fits together. This includes the thresholds, automating the deleting process, and a couple of other points. 

It’s important to consider the amount of noise one sees when dealing with bugs. We want to minimize the amount of bugs actual humans need to deal with—mostly because we don’t want to get overwhelmed with the sheer number of bugs. Naturally, you have to be careful not to strip out significant and relevant bugs!

Fin?

During our brainstorming session, we thought about our goals for the initiative. We came up with this…

For this to work properly, there are two things that need to be done:

  • Have a workflow/process in place for handling bugs
  • Get a good Bugsnag set up so that dealing with bugs is as easy as possible

After these are defined, every member of the frontend team should be aware of these processes and do their part to keep the number of bugs at a minimum.

This isn’t some super complex idea, nor is it as profound as I would like it to be. It summarizes the whole initiative in a couple of sentences, but is often overlooked when trying to get on top of this issue.

Doing it this way really does require additional work and will probably drive you out of your mind sometimes, but the payoff is huge! Think about the happier users, how your product will be more robust, and the amount of things you might learn that you weren’t aware of before. And can you really say that you’re tracking errors if you’re not resolving them in due time?

In a product of this size, you’re not going to cover every case that might happen with tests and your coding. This might sound a little demoralizing, but it shouldn’t be, it’s a normal thing! There are a lot of things that can go wrong in building an application, so in order to cover your bases even more, error tracking is a step in the right direction.

If you’re really interested in a particular subject we discussed here briefly, we’ll be posting more deep-dives related to specific implementations of the mentioned solutions, so stay tuned for that!

Davor Tvorić

Frontend Engineer at Productive. Excited about anything related to computer science. I spend most of my personal time reading and playing video games.
More From This Author

Related articles

Related jobs

The post So, You’ve Started Tracking Errors. Now What? appeared first on Building Productive.

]]>
https://productive.io/engineering/so-youve-started-tracking-errors-now-what/feed/ 0
Pull Requests—The Good, the Bad and Really, Not That Ugly https://productive.io/engineering/pull-requests-the-good-the-bad-and-really-not-that-ugly/ https://productive.io/engineering/pull-requests-the-good-the-bad-and-really-not-that-ugly/#respond Wed, 09 Nov 2022 08:34:20 +0000 https://productive.io/engineering/blog/ PR review workflow helps with code quality, sharing domain knowledge and mentoring. But every process comes with overhead.

The post Pull Requests—The Good, the Bad and Really, Not That Ugly appeared first on Building Productive.

]]>

Pull Requests—The Good, the Bad and Really, Not That Ugly

Ivan Lučin

VP of Engineering @ Productive. Frontend engineer under the hood. Outside of working hours—a happy husband, dad of two girls and a wannabe musician.

November 9, 2022

Recently, I stumbled upon an article on arkencyDisadvantages of pull requests.

I soon realized this was interesting stuff, worth sharing with my colleagues. Immediately I started writing a follow-up article, debating every claim made in the text.

We practice PR review workflow in Productive’s engineering team daily. This workflow helps us with:

  • Ensuring code quality and stability
  • Domain knowledge sharing in the team
  • Organized mentoring activities

Productive’s Engineering team builds one SaaS product and works on two massive codebases—the backend (API) and the frontend (web app).

Every process comes with overhead, and so does this one, but I’ll argue it’s worth it.

In this blog post, I’ll quote key points from the mentioned article and give my thoughts on the matter.

Now, let’s discuss the disadvantages of pull requests!

1. More Long-Living Branches, More Merge Conflicts

PRs promote developing code in branches, which increases the time and the amount of code staying in a divergent state, which increases chances of merge conflicts. And merge conflicts can be terrible, especially if the branch waited for a long time.

Yes, this is true. But it shouldn’t be that big of an issue if you practice a good distribution of work in your team.

Most products consist of many modules which are usually different screens or sections in the app. You should always divide work across those modules, in a way that one PR doesn’t interact with the other.

If your codebase is not that modularized, you can ensure a few good practices to avoid this issue:

  • Always split a big chunk of work into smaller, but functional PRs.
  • Rebase the branch daily and update it with new changes from the master/develop (I usually do this before every code review).
  • Always separate preparatory refactorings and merge them before implementing the actual feature changes. This is great advice given in the original article!

The most common mistake developers do is putting too much work into one PR, making both the review and merge process harder than it should be.

2. The Reviewability of a Change Decreases With Size

PRs tend to promote reviewing bigger chunks of code.

More often than not, developers fall into this trap. They think something like “I’ll just refactor this while I’m already here” or “I need to complete the whole thing before sending it for review”. This leads to oversized PRs and a slow development process.

3 PRs with 100 lines are reviewed and merged faster than 1 PR of 300 lines.

Of course, not all changes are the same. If we have 100 lines of boilerplate code, which is usually framework scaffolding, there’s no complexity there. Tests take a lot of lines but should be easy to read. Code with fewer dependencies will always be easier to grasp too.

Basically, the more a developer is experienced and familiar with the codebase, the more lines he/she is allowed to put in one PR. Less experienced developers on the project should strive to make their PRs as thin as possible.

3. Short Feedback Loop Makes Programming Fun

You code something up but it’s nowhere close to being integrated and working. You now have to wait for the reviewer, go through his remarks, discuss them, change the code…

I couldn’t agree more. There’s nothing more exciting in programming than getting a great idea, implementing it fast, and testing it out instantly.

The original author’s claim is that PR reviews kill that short feedback loop which makes programming less fun. But if that’s true, then it also means that:

  • Your team is producing large and overcomplicated pull requests.
  • You don’t have a good deployment and review environment setup.
  • You’re not coding features in safe-enough isolation.

Again, it all revolves around making small and easily reviewable PRs, but we’ve already acknowledged that, so let’s move on.

If you do have a large PR waiting review, that doesn’t mean you can’t try it out in the wild. You could easily deploy the code to a staging environment, or even production, but on a separate domain so only you and your team can try out the new changes.

At Productive, for our main frontend app, we have an automated PR deployment setup. When you create a new PR on Github or push commits to an existing PR, a Github action is triggered that deploys the code to the “review” environment.

It takes the name of the git branch and deploys the frontend app to the subdomain with the same name. For example https://cool-new-stuff.review.productive.io.

Voilà, now you can try your PR changes in the live environment two minutes after you’ve created the PR.

Plus, there’s another Github action that posts a comment with a test link, so you don’t need to type it into the browser’s URL bar manually:

This is a frontend app example hosted as a static asset on a CDN, but you could do it similarly with backend apps.

There’s another mechanism for achieving a short feedback loop which is safe if done properly. With feature flags, you can ensure that your PR is not introducing any breaking changes and that new code is implemented in isolation from existing features.

Feature flags allow you to try the new changes in an isolated scope, without changing anything in the rest of the system. The scope can be either one user, one account, or just one API request. It’s a powerful mechanism that our team uses on a daily basis. It allows us to push new changes to the live environment rapidly, without worrying about breaking things.

4. Reviews Tend To Be Superficial

Proper review takes the same amount of focus as actual coding. Why not pair-program instead?

I agree that PR reviews tend to be superficial, especially when there’s too much to review. That only means that the reviewer is doing their job poorly. You can recognize this situation when you see a complex PR that only has code-style comments like “Fix naming” or “Wrong indentation”, etc.

If the PR seems like it’s too complicated—why not pair-review instead?

Pair programming (not to be confused with pair-reviewing) is useful for mentoring junior developers, but it’s a waste of time in a lot of other cases. That’s because you’re not solving complex problems all the time.

A better way to do it is to pair-review the PR with the author after most of the boilerplate is done and proper research has been made. Then you only talk about the complex stuff and you can leave the author of the PR to explain their thought process in detail.

There’s one more thing here… Programmers usually get this “feeling” when something stinks about their solution. They should be honest and leave comments in the PR, in every place where they feel they could be doing something wrong. That greatly increases the reviewability of the PR.

5. Merging Is Blocked by Remarks That Shouldn’t Be Blocking

Remarks made by the reviewer can fall anywhere on the spectrum of whether they should block merging or not: from a mistake that’ll bring production down to cosmetic suggestions or opinions.

These situations happen quite often with inexperienced reviewers. When commenting on the PR, you should tell the author if the comment is a merge-blocker or not, and never insist on details too much.

When I’m working with inexperienced developers, I’ll usually tell them exactly how to fix something, with an explanation. For non-blocking mistakes, I’ll just comment to watch out for that in the next PR. Usually, I’m the one to merge the PR, so they don’t have to wonder whether the PR is finished or not.

When reviewing experienced dev’s PR, I’ll tell them what I think about the problematic places in the code, but I’ll mostly approve the changes and leave them to the author to do the fixes the way they want to.

Not everything the reviewer says is always correct or the right thing to do. The author should be the one to decide on the comments—because it’s their work.

6. It’s Easier To Fix Than To Explain the Fix

The original author has to understand it first, agree with it, and then is expected to implement it. Often it’s better to let the original author merge his thing, and let the reviewer implement his remark post-factum?

A lot of times it’s hard to explain the fix to the author and it would be more efficient just to implement the fix yourself. But merging the unfinished PR could be dangerous, so I’d never suggest that. You’d also be missing the opportunity to educate the original author about the problem.

Pull requests don’t have to be done by only one person. Why wouldn’t you, the reviewer, just pull the branch, implement, and push the fixes back upstream? That way the author gets notified about what you did and you both have an opportunity to discuss the issue.

That’s also an effective thing to do when there are a few simple fixes required on the PR. Let’s say you notice a typo somewhere in the PR. It’s much faster to fix it yourself than to leave a comment and wait for the author to do the fix. You could do that directly in Github and it would take like 30 seconds.

7. Developers Are Slower To Adapt the Responsibility Mindset

The second one knows that every line they write can screw up things for other developers or even bring production down. They watch their step, they know they are the only one responsible for this change. It shortens the delay between making a mistake and seeing the effect of it.

This is an interesting and important claim. Can your business afford to tear the live server down just to teach the developers some responsibility? Sometimes it’s worth it, but in most cases, you wouldn’t want to do that.

Code stability is not the only reason why we should be reviewing our PRs. There are also benefits of mentoring, knowledge sharing, better release organization, feature completeness, structured discussion around a diff, etc.

At Productive, we encourage people to self-merge PRs without a review when they’re confident that the changes are fine. The developer should have the freedom to do that in the part of the codebase where they have more ownership. I believe this is how the responsibility mindset can be trained. When people build something from the ground up, they will feel the responsibility to keep everything in great shape.

8. PRs Discourage Continuous Refactoring

It’s good to follow boy scouts’ rule: always leave the place better than it was before. With PRs, though, this rule is harder to apply.

PRs will slow you down on refactoring. When you realize that some refactoring is needed, you need to switch to another branch to implement the refactoring separately, submit the PR to review, wait for the approval and merge the changes back into the original branch.

But it’s still better to do it that way, in my opinion. Refactoring PRs shouldn’t be complicated to review since there shouldn’t be any changes in the logic, only the code structure. That’s especially true if you have good test coverage. If you don’t, then maybe you should write the tests first?

Maybe the refactoring PR doesn’t need to go through the review process if everything is trivial. If it does, then mention to the reviewer that this is a refactoring-only PR that’s blocking feature development and the reviewer should prioritize the approval.

Having good team communication around PRs will minimize most of the downsides of the PR review process.

9. Negative Emotions

Mandatory PR reviews can induce way more negative emotions than needed. We all have limited emotional budgets — it’s better not to waste it on avoidable stuff.

When it comes to pull request reviewing, the responsibility is both the author’s and reviewer’s. There’s one simple rule to follow:

Don’t be a prick when reviewing or authoring the PR.

The original article is basically saying that we should let developers do what they want because they might get offended by the review comments.

Obviously, that’s ridiculous. This doesn’t have anything to do with PR reviewing itself—it’s a communication problem. If your engineering team doesn’t know how to communicate, then you’ll have bigger issues than developers offended by a PR review.

10. How Do You Switch to Branches With Migrations

You obviously sometimes need migrations while working on a branch. What do you do if you then have to switch back to another branch locally? Cumbersome.

Well, just do the migration separately on the main branch, before implementing the remaining logic in the PR. The world won’t collapse if you don’t always work on branches with PR reviews. You can always omit the process if you have a good reason for it.

Conclusion

The original article contains a list of suggestions on how to improve your team’s PR workflow. Those are all great ideas, which I encourage you to try. Thanks to arkency for writing a great and educational article! We’ve also published a copy of this article on Medium.

As with other organizational processes, we shouldn’t take them too seriously because they tend to generate overhead and slow work down. We should be pragmatic about PR reviews and when we notice they’re becoming a burden—we can skip them sometimes.

Don’t follow the rules blindly, try thinking with your head and do the right thing depending on the situation you’re in.

And a little remark for the end—let’s all be humble and respectful towards each other while reviewing each other’s code!

Ivan Lučin

VP of Engineering @ Productive. Frontend engineer under the hood. Outside of working hours—a happy husband, dad of two girls and a wannabe musician.
More From This Author

Related articles

Related jobs

The post Pull Requests—The Good, the Bad and Really, Not That Ugly appeared first on Building Productive.

]]>
https://productive.io/engineering/pull-requests-the-good-the-bad-and-really-not-that-ugly/feed/ 0