But as this happens, questions arise, such as who supports these applications? And who will make the updates if there is a feature request or bug?

Many low-code applications are often created by a single developer, inherently leading to a single point of failure.

And don't let the advertised simplicity of low-code trick you into thinking anyone can edit the app, fix any issues, and add new features. Low code can still contain complexity, and complex solutions can quickly become a problem for organizations and teams that leverage dozens, if not hundreds, of other low- or non-low-code dependencies.

This doesn't mean that organizations should strictly restrict who can create these applications. Doing so would contradict the very purpose of low code. It's a model that empowers stakeholders themselves to rapidly prototype ideas and develop low-cost solutions to problems that, in traditional development, might cost millions of dollars.

In this low-code world, both organizations and developers need a plan. Developers, specifically, should have a plan to transfer knowledge of their products, whether working in a team or independently.

How to Simplify Complexity

Our relatively small team has created numerous low-code solutions, primarily leveraging Microsoft's suite of products. Some of these solutions are simple low-code canvas apps, while others contain hundreds of dependencies that are anything but low-code.

We've learned, sometimes the hard way, the importance of ensuring maintainability in our development. This means supporting the applications we build and enabling existing and new team members to support them in the future.

Initially, we found ourselves drawn to the premise of being able to create products that solve problems quickly. Before we knew it, we had our own problem: how do we support the array of these products, ensuring that not just us but new team members could do so as well?

Slow Down to Speed Up

This might sound contrary to the low-code paradigm, but taking frequent pauses to consider the long-term impacts of your decisions is critical to ensuring the tools you build today can be supported tomorrow.

This does not mean reverting back to the speeds of traditional software development, but you should not consider building low-code products as a race to the finish line.

Pair Programming

Incorporating traditional software development practices can significantly benefit the low-code movement. Even if your applications involve little to no conventional code, concepts like pair programming can be effectively applied when building low-code products.

Take, for example, the process of building a Power App. Traditionally, only one person could edit an app at a time. Although that limitation has changed—multiple people can now edit an app simultaneously—defining a collaborative process remains crucial.

Our team often employs a primary "driver" approach, where one member leads the development while another observes, providing real-time feedback and suggestions.

This method keeps everyone engaged and helps mitigate the effects of tunnel vision on the product. And this collaborative approach is especially valuable for more complex aspects of the application.

For more straightforward tasks, we often work in parallel but stay closely connected via Teams or Zoom, ready to coordinate and ensure each different component is part of a cohesive whole.

Application/Code Reviews

Low code doesn't mean no code. It is challenging to create robust applications with drag-and-drop alone. Even something like Power Apps has its own language called Power FX.

Schedule time each week to walk through or review others' applications to become familiar with their creations. Look for places where things can be improved, and be ready to accept feedback on your creations, too.

If you're using traditional code in your project, some of this can be accomplished with PRs. For purely low-code implementations, keep a document of changes and have a sign-off process to ensure other team members can access new changes.

For example, imagine adding a new screen to a Canvas app, allowing users to update personal settings. That change should be documented as unreviewed until at least one other team member has reviewed and signed off on this new feature.

Get Other Team Members Involved

If you're on a team, each product should involve at least two people to avoid single points of failure. Ensure each product has a primary and secondary developer or product owner. For larger teams, allow that secondary role to rotate, ensuring each member is more intimately involved with the team's products.

One way to get others involved and up to speed is to have other team members add new features or fix bugs in existing products under the guidance of the primary or lead developer. This knowledge transfer will help cultivate ownership in the various products your team supports, leading to higher engagement and motivation.

Additionally, as the workload is distributed more evenly across the team, bottlenecks are reduced, allowing for more expeditious handling of fixing bugs and enhancing products.

When a Hands-On-Approach isn't Possible...

Much of what I describe above is an attempt to get others involved with projects. The more we touch these things, the better we will understand them.

Inevitably, however, when this hands-on experience isn't possible, it is essential to have practices that can mitigate the effects of isolated development—that is, a development done by one or just a few people.

The two most important things we can do are create and maintain comprehensive documentation about our products and use standard practices as much as possible. We'll talk about documentation first.

Document, Document, Document

As you've probably experienced, the low-code movement allows applications to be created quickly. The more applications exist, the fewer touchpoints we have with older ones. While those touchpoints are critical to the knowledge transfer process, relying on them alone isn't enough.

Whether you're on a team or a solo developer, creating documentation that describes each aspect of your products is critical. For small projects, this may be a simple text document. For larger projects, you could utilize a SharePoint site. Of course, as products become even more complex, the various dependencies will likely have their own documentation (for example, Git repositories).

Here is an example of how you might document a product you are building:

Let's say you have an application that allows users to reserve a conference room for meetings. That application consists of a user interface (such as a Canvas app) and custom code that creates a follow-up reminder for the person who reserved the meeting a day before. This reminder could send an email to remind the user about the meeting, and if the meeting is no longer occurring, encourage them to cancel the reservation. Finally, this product could also have a reporting element, where administrators can see conference room utilization over time to better understand demand.

Here is how you might document this project:

1. Establish a single source of truth about this project, such as a SharePoint page.

2. This page briefly describes the project, the product owners, and the lead developers.

3. The page would also briefly describe this project's components (Canvas app, custom code, and reporting dashboard).

4. Finally, you would include documentation on any easy-to-overlook aspects or non-standard project implementations (more on standardization later).

The SharePoint page handles the high-level overview of the project and gets you pointed in the right direction. Regarding the individual components, the Canvas app will include comments and notes in the version history, and your custom code will leverage Git and often include a detailed readme.

Documentation can be challenging, but it is critical. While documentation should be comprehensive, it should complement the hands-on knowledge transfer techniques described above.

Standardize as Much as Possible

Whether it is low-code or traditional development, it is important to have standard practices. This is even more important when talking about low code because of the speed at which things can be developed and potentially get out of control.

From project planning, design, development, and testing to cross training team members, make time to create standard practices for each phase.

Standardization shouldn't be considered a way to eliminate the need for cross-training and documentation but rather a way to complement those stages and reduce the time needed in those areas.

If you can approach a problem the same way every time, you can spend time discussing those non-standard and easy-to-forget parts of what you're building.

Here are some questions to get you started:

1. What big-picture steps will each application require? Who will be involved in those steps?

2. What tools will you use? (for example, Power Apps, Appian, Pega)

3. Can you support traditional development? If so, how will that look?

4. What is your philosophical approach to development? For example, should you design the user interface or business logic first? What database will you use? (for example, SharePoint or Dataverse)

5. What conventions will you use in your code? (for example, naming conventions for screens and variables)

6. What does this knowledge transfer or cross-training process look like? Do you have dedicated times each week to review each other's work?

Of course, this list goes on. The more you learn, the more you'll realize what needs to be discussed. Get started by creating a Standard Operating Procedure (SOP), and be prepared to edit it early and often.

What if I am a Solo Developer?

If you're a solo developer, it may be easy to think that the recommendations above don't apply. But this couldn't be further from the truth. Creating and maintaining a knowledge-transfer framework is even more critical as a solo developer. While co-developing and pair programming are not directly applicable, the concepts still apply.

For example, take time to meet other developers and ask for feedback. At a minimum, it will be an excellent way to meet other people doing the same thing. And, of course, with AI taking a front row in programming, you can always leverage AI to help you learn new techniques and optimize the things you are building.

Finally, documentation and standard practices are just as necessary for the individual developer. First, if you ever work with others, you'll have a reference for your work. Second, these things will act as an external reminder of how you intend to solve development-related problems in the future.

Conclusion

While low-code platforms offer incredible speed and flexibility, they can also introduce challenges when it comes to maintenance. Rapid development, if not managed carefully, can lead to issues that undermine the long-term success of your applications.

But by intentionally slowing down and establishing a clear plan for knowledge transfer, you can safeguard the future of your critical products. This approach ensures that applications remain supported and sustainable, both now and for years to come.

Stay curious.

Found this helpful? I write about practical automation, productivity systems, and building smarter workflows — without the jargon. Visit me at brandonwoz.com.

Coding can be challenging, but it can become a lot easier if you have the right strategies and tools.

After all, as noted software engineer and writer Joel Spolsky says, "it is harder to read code than to write it."

One way to make your development projects more successful is with collaborative coding. This refers to the process of working on the code with a team or with another developer. In a project that uses collaborative coding, each team member helps build the code and checks it for bugs or errors.

Working in pairs or teams helps finished code contain fewer mistakes and bugs, and this results in better code quality and projects being completed more quickly.

It also enables faster debugging and greater project resiliency, as this setup makes it easier for other developers to take over in case one of the developers has to leave the project.

But collaborative coding won't produce all of these benefits by default. Making them happen comes down to how you implement your collaborative development strategy and how you execute it. Here are four points to consider when doing so.

You Need a Secure Development Process

Although having multiple sets of eyes checking a project's code should produce a net benefit for the code's security — it can also introduce a new type of vulnerability into the mix. This is because sharing code through a collaboration platform creates the possibility of a data breach.

Humans, after all, are the weakest link in the cybersecurity chain. So, the larger the team, the greater the odds that someone will make an unforced security error during development.

And things like exposed or stolen login credentials can endanger a project — especially one that is designed to handle sensitive information like banking and personal details.

This means that project managers must choose a collaboration platform that's built with security in mind. Some collaborative coding platforms already have built-in security features, but others do not. And different types of coding projects will call for different feature sets, so there's no one-size-fits-all solution.

There are plenty of collaborative coding platforms that may fit the bill, however. Teletype, for example, comes with end-to-end encryption and the option to use self-destructing messages.

Another popular option is Brackets, which comes with data protection when interacting with third-party plugins and has a mechanism for preventing unapproved access and privilege escalation.

Some teams or developers might use established collaboration platforms not specifically designed for coding. Microsoft Teams, for instance, can facilitate casual coding collaboration. And although it's not an inherently insecure system, it has weaknesses that developers can address with an additional Microsoft Teams Security solution.

These solutions include features like malware protection, URL protection, access control over confidential data, compliance tools, and security alerts – which all improve platform security significantly.

Regardless of the platform you choose, though, it is important to use security tools or to install third-party security solutions that ensure the best possible security for your project.

Choose the Right Platform for the Job

It's also important to recognize that security isn't the only consideration when you're choosing a collaborative coding platform.

It's also critical to choose one that will provide every team member with the tools and resources necessary to do their job. The right platform should meet the following criteria:

It's made for a specific programming language or ecosystem

There are many benefits in using a platform that is created for a specific programming language. First, it most likely has all of the tools necessary to efficiently work on a project in a particular language. And it won't have unnecessary features added to cater to other requirements and preferences.

A language-specific platform is also designed with best practices in mind for developers working with particular languages or frameworks. So, for example, when working with dynamic programming languages such as Go, Ruby, and Python, it is preferable to use a platform like Cloud9.

It's fast to setup

Ideally, everyone involved should already be familiar with the collaborative coding platform that you'll use. But if this isn't the case, it's important to choose one that is easy to learn with minimal to no configuration involved.

A platform that requires IDE, server, terminal, codebase, and library configuration along with other setup procedures is not the most suitable option for live coding between pairs or teams of developers.

It should have a customizable user interface

Programming is a heavily detail-driven job and developers tend to have their own preferences when it comes to the user interface so they can work easily and conveniently.

Forcing everyone to use a platform they are not comfortable with is not a good way to proceed with collaborative coding. So it helps to have the option to modify the UI or dashboard to some extent.

The bottom line is that the collaborative coding platform should be easy to use for everyone. Developers may be highly skilled people, but not everyone is a master of everything. Those who are collaborating should agree on a platform and working arrangement that works for everyone.

Define Clear Team Roles at the Outset

We can categorize collaborative coding into three general setups:

• pair programming
• mob programming, and
• code sharing.

And understanding the inner workings of each of these setups is important, as different coding projects require different setups.

But it's equally important to understand the roles of the team members in each setup and to define them before beginning to code.

As the phrase suggests, pair programming involves two participants. Usually, one serves as the driver and the other acts as the navigator. The driver writes the code while the navigator reviews the output.

In this setup, the driver is responsible for the tactical aspects of the job while the navigator sets the strategic direction of the code. The two may then switch their roles to have a more thorough look at what they have produced.

Mob programming is similar to pair programming but involves more than two people. To avoid making it a chaotic or disorganized arrangement, it is also important to have the driver-navigator role assignments.

It is slightly more complicated, though, because there are more than two developers who have to agree on how to assign the driver-navigator roles. This means that clear communication and mutual respect are crucial.

The code-sharing setup does not require a driver-navigator dynamic. Instead, the collaborating developers only share their respective code to allow each other to review, modify, debug, or add to each other's code.

This is the type of collaboration that open source developers tend to rely on because it allows newcomers to participate at will and existing developers to pause their work whenever they need to.

The participants here may work on the code together in real-time or asynchronously. What's important is that they have a reliable system for version control.

That's where version control systems like Git excel. They help teams to avoid doing duplicate work and make sure that all developers are reviewing, revising, or adding to the latest version of the code at all times.

Create Skill Balanced Teams for Best Results

While some would consider collaborative coding as an opportunity to learn from more experienced and proficient coders, that doesn't mean every collaborative project is conducive to that.

This is because for certain types of projects, having too much of a disparity in the skill level of team members can grind the whole project to a halt.

This is a problem that feeds one of the biggest criticisms of collaborative coding as a development method. When team members must contribute as equals but lack the skills to keep up, progress stalls. When time is of the essence, creating a skill-balanced team is the only option.

That said, collaborative coding can be an opportunity for collaborative learning, but only when deadlines aren't involved. In that scenario, team members can take their time to learn from the work of their more experienced peers. And in the end, everyone benefits from the experience.

But if the goal is to make the project a collaborative learning endeavor, it is important to make that clear from the get-go. Otherwise, the more experienced developers could feel like they've been duped into providing training instead of getting the project done. And that never ends well.

Conclusion

The advantages of collaborative coding are undeniable — but there are drawbacks to consider too.

So, before deciding to go into the collaborative route, it is important to carefully scrutinize the pros and cons as they relate to a specific project.

And for developers who wish to try their hand at collaborative coding, it's a good idea to get familiar with the popular tools and platforms used for such projects beforehand. That way, both the project planners and team members will get the most out of the collaborative process — but without encountering some of the issues that it can entail.

Featured photo by snowing 12 - stock.adobe.com

In this tutorial, you will learn how to work in a team with a central repository on GitHub. You will work on issues, commits, pull requests, code reviews, and more.

I don't consider myself an expert on Git, but I have learned a lot about it in my first month working as a software developer.

I wrote this tutorial to share how Git is used in professional environments. Bear in mind that there is not just a single way of using Git – so this is just one approach, and it may differ from what you see in your professional career.

A good read to start working with Git workflows is this Comparing Workflows tutorial.

The Project

Harry and Hermione had the great idea of building a SaaS app to allow people to build their own potions online and share them with the rest of the world. They named it Potionfy, and this will be their first start-up.

They decided to use GitHub as the central repository in which all their work was going to be stored. They chose React and Ruby on Rails as the app technology stack.

The Team

Potionfy will be bootstrapped by Harry and Hermione themselves by using their savings. They will work their home garage and they expect to have an MVP ready in 4 weeks.

Let's see how they will work together in building the SaaS product and the obstacles they will have to overcome in doing so.

Initial Project Setup

This project will use two fictional team members – Harry and Hermione – with two separate GitHub accounts. So you may want to start creating two accounts on GitHub for this.

Bonus: in order to simplify things, if you have a Gmail account you can use your Gmail address with a plus and a string after the first part of it, and all email communications will be centralised in one account, like so:

my_email_address+harry@gmail.com
my_email_address+hermione@gmail.com

More on this here.

Step 1: How to create two different GitHub accounts

In order to follow along with this tutorial, you'll need two different GitHub accounts. I chose to create two, but you can just use your own and create another one. Here is how my set-up looks:

Step 2: How to set up your local development environment

We are going to use a local development environment and set up Git on it. I decided to use a virtual machine running Linux, but you can use your own environment (I just want to avoid any kind of configuration problem with Git).

We have to make sure Git is installed in our system:

git --version

This command should return the version of Git that is installed in your system. In my case, my virtual Ubuntu didn't have it installed, so I ran:

sudo apt install git

Step 3: teamwork considerations

Harry will be the one working locally in our development environment, and Hermione will choose to work directly on GitHub by using an online VSCode (more on this later).

How to Get Started Working on the Project

Step 1: How to create the repository and build the team (for free)

Hermione is the leader of the team, as she is more experienced in coding, so she has decided to create a new repository to host the code for the SaaS product.

To create the repository, she simply used the GitHub web interface and clicked on the Repositories tab, and then on the New button. She named the repository potionfy and she added a short description and a Readme.md file.

After the repository was created, she invited Harry to work on it. To do so, she clicked on the Settings tab in the potionfy repository, then in the Manage access option, and finally in the Add people button.

By entering Harry's GitHub username (or email address) in the pop-up window and clicking on the Add Harry(...) to this repository, she managed to send the invitation to Harry.

A couple of seconds later, Harry received the invitation to his email:

He accepted it, and by doing so, both team members were ready to start working on their project.

NOTE: In case the invitation link does not work (as in my case), Harry needs to go to Hermione's GitHub profile, click on the potionfy repository, and accept the invitation there:

Step 2: How to create a file

Hermione started the project by creating the initial file the Potionfy SaaS product will use: index.html.

In order to do so, she created the file using the GitHub web interface by positioning herself in the repository and clicking on the Add file > Create new file buttons.

Then she added the name of the file, its content, and a meaningful commit message. After clicking on the Commit new file button, the file was created on the repository.

Step 3: How to create an issue and work on it

Hermione needs to move on to work on the marketing related to Potionfy launch, so she told Harry to add a simple landing message to the index.html file. So, she proceeded to create an issue in the repository by clicking on the Issues tab and clicking on the New issue button.

After the issue was created, Harry took a look at it (also by going to the issues tab in the Potionfy repository) and let Hermione know that he will be working on it by leaving a comment and assigning the issue to himself.

By working with this dynamic, the team will know who is working on what.

Step 4: How to set up the local development environment

In order to work on the project's index.html file, Harry chose to work locally, so he needed to clone the potionfy repository in his development environment (the Linux virtual machine).

The first thing he had to do was set up the SSH keys to work with GitHub. He followed GitHub's Generating a new SSH key and adding it to the ssh-agent tutorial to do so. He then added the key to his GitHub account, following the Adding a new SSH key to your GitHub account tutorial.

Then, Harry opened Hermione's repository on GitHub and copied the link to clone it:

Now in his local development environment, he created a new directory in which all his work would be centralised:

$ mkdir ~/development
$ cd ~/development

Finally, he cloned the repository by typing git clone and pasting the code he just copied from GitHub (which is the address of the repository):

$ git clone git@github.com:Hermione-Colo-Codes/potionfy.git

In this way, he now has a local copy of the repository and he is ready to start working on it.

$ ll
total 12
drwxrwxr-x  3 parallels parallels 4096 Nov 17 07:34 ./
drwxr-xr-x 23 parallels parallels 4096 Nov 17 07:33 ../
drwxrwxr-x  3 parallels parallels 4096 Nov 17 07:34 potionfy/

GitHub workflow

In order to work on a repository, this is the workflow GitHub recommends:

1. Create a branch
2. Make changes
3. Create a pull request
4. Address review comments
5. Merge your pull request
6. Delete your branch

For more information about this, you can read this document.

Step 1: Create a branch

As it is a good practice not to work on the master branch directly, Harry created a new branch related to the issue on which he will be working.

He chose to do this on the GitHub repository, but he could have done the same in his local environment using Git commands.

He chose a meaningful name and prefixed the name with the number of the related issue (which is 1, in this case).

More information about how to create a branch on GitHub can be found here.

Step 2: Work on the branch locally

After the branch was created, Harry started working on it.

git pull

The first thing he did was a pull of the whole repository so he could see the branch in his local development environment.

~/development/potionfy$ git pull
Warning: Permanently added the ECDSA host key for IP address '13.237.44.5' to the list of known hosts.
From github.com:Hermione-Colo-Codes/potionfy
 * [new branch]      1-add-landing-message -> origin/1-add-landing-message
Already up to date.

git checkout

With the new branch in his environment, he switched to it by using the git checkout <name_of_branch> command. After doing so, he ensured he was working in the correct branch with the git branch command.

~/development/potionfy$ git checkout 1-add-landing-message 
Branch '1-add-landing-message' set up to track remote branch '1-add-landing-message' from 'origin'.
Switched to a new branch '1-add-landing-message'

~/development/potionfy$ git branch
* 1-add-landing-message
  main

Solve the issue

Harry started working on solving the issue. In order to do so, he opened the index.html file and added a h1 header to it.

After the changes were made, he saw how Git reacted to this change.

~/development/potionfy$ git status
On branch 1-add-landing-message
Your branch is up to date with 'origin/1-add-landing-message'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   index.html

no changes added to commit (use "git add" and/or "git commit -a")
parallels@parallels-Parallels-Virtual-Platform:~/development/potionfy$

He then added the file to the staging area with the git add command and committed the change with the git commit command.

~/development/potionfy$ git add -A

~/development/potionfy$ git commit -m "Add landing message. #1"

~/development/potionfy$ git status

Note how the commit message also includes the id of the issue, which in this case is #1.

Push to the repository

The next step Harry needs to do is to push the changes to the repository.

~/development/potionfy$ git push

Create a pull request

Harry then clicked on the Compare and pull request button in the GitHub repository (making sure his branch was selected in the branch left drop-down menu).

This pull request will be analysed by Hermione and she will decide if it can be merged to the master branch or not.

Quick recap so far

Up to this point in the tutorial, we learned how Harry and Hermione decided to build a SaaS app to allow people to build their own potions online and share them with the rest of the world. They named it Potionfy.

Hermione created a remote repository, then an issue to address the task of building a landing page, and how Harry worked on that issue locally and created a pull request once he finished working on it.

Now, we are going to see:

• how Hermione reviews Harry's code,
• how the code is merged on the master branch,
• the decision of using a develop branch,
• how the team works in the develop branch and merges changes into main,
• and how the team solves merge conflicts.

How to Do Code Reviews

Step 1: How to create a code review

Hermione has finished with her marketing and promotion tasks, and she now has time to review Harry's code.

In order to do so, she opens the GitHub repository and clicks on the Pull requests tab to find Harry's pull request.

After clicking on it, she then clicks on the Commits tab, and finally in Harry's last commit (this is just one way of accessing the files modified on the pull request).

She is not entirely convinced about the <h1> code, so she clicks on the plus icon that appears when she hovers that line of code, and writes a comment to Harry. Finally, she clicks on the Start a review button.

As she has no other comments about the code, she now clicks on the Review changes button to make the review visible to the rest of the team.

You can find more information about making reviews in this Reviewing proposed changes in a pull request article.

Step 2: How to address the review and create a code change

Harry checks his pull request and finds a new conversation there: Hermione's review.

Harry answers Hermione's comment and clicks on the Resolve conversation button.

Now that the conversation is resolved, Hermione can submit the review indicating that there are requested changes so Harry can actually work on them.

Note: this is just one version of the review process in GitHub, and it can differ from the actual way your team chooses to handle them.

Harry checks the pull request again and finds that it has Changes requested.

Step 3: How to implement the changes

As Harry likes to work locally, he continues working on the branch he had created in order to implement the code changes.

$ git checkout 1-add-landing-message

Once he is sure he is working on the correct branch, he makes the changes in the index.html file.

Note: for simplicity sake, we are not creating a separate CSS file here.

Once Harry finishes tweaking the code, he stages the changes, commits them (making sure to include the id of the issue because he is still working on it), and pushes them to GitHub.

$ git add -A

$ git commit -m "Add colour and remove text. #1"

$ git push

Step 4: How to merge the pull request

Now it's Hermione's turn. She goes to the pull request and finds a new commit: the one Harry did and pushed to GitHub.

She then clicks on the Files changed tab and finds the ones that she suggested implemented on the index.html file.

As she is satisfied with the changes, she proceeds to approve them by clicking on the Review changes button and selecting the Approve option.

Harry sees that his pull request was approved by Hermione, and he proceeds to merge it into the main branch of the project.

He decided not to delete the branch, as he wants to leave it there for future reference (although it would be a good idea to delete it).

As Hermione is satisfied with how the issue was solved, she proceeds to close it by going to the Issues tab and clicking on the Close issue button.

If you want to see a graphical representation of the whole process up to this point, you can click on the Insights tab and then on the Network option. You will be able to actually see how the branching and merging were performed.

How to Use a develop Branch in Git

When working with real projects, merging changes into the main branch like you saw up to this point is not recommended.

Instead of working directly with the main branch (often called production), you will be working with a develop branch. You will be branching issues out of that develop branch and merging them back into the develop branch.

Once a group of issues have been solved, that develop branch will be merged into the main (or production) branch, usually denoting a version change in the app.

Hermione is aware of this, and now that the landing page is live and accessible to customers, she decided to preserve that production environment and work on a development branch.

In order to do so, she creates a develop branch out of the main one, so she and Harry can work on that branch without impacting the production environment.

How to Handle Merge Conflicts in Git

Hermione wants to add a new feature to the landing page: a form to capture clients' emails. In order to do so, she creates a new issue.

Once the issue is created, Harry decides to start working on it. To do so, he branches out from the develop branch (by selecting that branch on the GitHub interface) a new one called 3-email-form (including the issue number at the front to make it clear how this branch will relate to the issues).

He then pulls that branch locally and starts working on it.

$ git pull

$ git checkout 3-form

Harry decides to include a simple form into the index.html file:

<form action="mailto:hermione@potionfy.com" method="post" enctype="text/plain">
Name:<br>
    <input type="text" name="name"><br>
    E-mail:<br>
    <input type="text" name="mail"><br>
    <input type="submit" value="Send">
    <input type="reset" value="Reset">
</form>

Note: This code is just to exemplify how Harry is working on a file and it's not how this type of form could actually be built.

Harry stages and commits his changes locally using the Contact form. #3 message.

$ git add -A

$ git commit -m "Contact form. #3"

$ git push

Before Harry could create a new pull request, Hermione decides to build a placeholder for the form on the index.html file on her own. In order to do so, she creates a new branch out of develop called 3-email-form-placeholder.

To work on the index.html file, she uses the GitHub online code editor (basically, a VSCode for the web). In order to open it, she just presses the . key on her keyboard and the GitHub page is transformed into a VSCode interface (like magic 😉).

She then proceeds to add the following code to the file:

<form action="mailto:harry@potionfy.com" method="post" enctype="text/plain">

</form>

After saving the file, she commits the changes right there on her browser window by using VSCode's graphical interface:

Once the commit is complete, she opens GitHub again and decides to create her own pull request and merge her changes to the develop branch.

On the other hand, Harry also decides to create a pull request to merge his changes into the develop branch.

At this point, GitHub lets him know that his pull request won't be able to merge automatically to the develop branch.

Harry supposes that his branch is no longer reflecting the state of the develop branch and that the develop branch has changed because someone else merged changes affecting the index.html file on which he was working on. Nevertheless, he proceeds to create a pull request.

What he sees next is GitHub's way of letting him know that there is a conflict affecting the file he modified. He proceeds to click on the Resolve conflicts button.

He can now see that the index.html indeed was modified, and the changes made to that file are affecting the lines he himself modified.

For more information about solving conflicts, you can read the Resolving a merge conflict on GitHub article.

Harry proceeds to modify the file directly on the GitHub site to remove the conflicting changes and then clicks on the Mark as resolved button.

Once the conflict is marked as resolved, he clicks on the Commit merge button.

Finally, his branch was conflict-free and he can merge his pull request (assuming Hermione reviewed his code and approved it, just as she did earlier).

Conflicts ofter arise when teammates are working on different branches that affect a common file. A great way to prevent merge conflicts is to do a pull request on the develop branch, merge that updated develop branch into the branch you are working on, and then do a push followed by a pull request.

$ git branch
x-my-branch # This is an example name

$ git checkout develop

$ git pull

$ git checkout x-my-branch

$ git merge develop

# You make some changes on the files of the x-my-branch branch

$ git add -A

$ git commit -m "<a message>"

$ git push

Final Thoughts

After working on their landing page, Harry and Hermione managed to get lots of email addresses from potential customers and continued developing their MVP. They managed to get funding from a local venture capital firm, and they are now in the process of hiring other developers to launch Potionfy to the public.

I'm sure they would love to take a look at your resume to consider you for a position in their company, so good luck!

🗞 If you enjoyed this article, you may like other articles I publish. The best way to know about them would be by subscribing to my newsletter.

🐦 You can follow and contact me on my Twitter account.

Cheers!

Damian.-

You might feel uncertainty when encountering the Git commit message, unsure how to properly summarize the changes you've made and why you've made them. But the earlier in your career you can develop good committing habits, the better.

Have you ever wondered how you can improve your Git commit messages? This guide outlines steps to elevate your commit messages that you can start implementing today.

This article assumes you already understand basic Git workflow. If not, I suggest reading through the Git Handbook.

It is also important to note that you should follow your team's conventions first and foremost. These tips are based on suggestions based upon research and general consensus from the community. But by the end of this article you may have some implementations to suggest that may help your team's workflow.

I think git enters a whole other realm the moment you start working in teams -- there are so many cool different flows and ways that people can commit code, share code, and add code to your repo open-source or closed-source-wise. — Scott Tolinski, Syntax.fm.

Why should you write better commit messages?

I challenge you to open up a personal project or any repository for that matter and run git log to view a list of old commit messages. The vast majority of us who have run through tutorials or made quick fixes will say "Yep... I have absolutely no idea what I meant by 'Fix style' 6 months ago."

Perhaps you have encountered code in a professional environment where you had no idea what it was doing or meant for. You've been left in the dark without code comments or a traceable history, and even wondering "what are the odds this will break everything if I remove this line?"

Back to the Future

By writing good commits, you are simply future-proofing yourself. You could save yourself and/or coworkers hours of digging around while troubleshooting by providing that helpful description.

The extra time it takes to write a thoughtful commit message as a letter to your potential future self is extremely worthwhile. On large scale projects, documentation is imperative for maintenance.

Collaboration and communication are of utmost importance within engineering teams. The Git commit message is a prime example of this. I highly suggest setting up a convention for commit messages on your team if you do not already have one in place.

The Anatomy of a Commit Message

Basic:

git commit -m <message>

Detailed:

git commit -m <title> -m <description>

5 Steps to Write Better Commit Messages

Let's summarize the suggested guidelines:

1. Capitalization and Punctuation: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase.
2. Mood: Use imperative mood in the subject line. Example – Add fix for dark mode toggle state. Imperative mood gives the tone you are giving an order or request.
3. Type of Commit: Specify the type of commit. It is recommended and can be even more beneficial to have a consistent set of words to describe your changes. Example: Bugfix, Update, Refactor, Bump, and so on. See the section on Conventional Commits below for additional information.
4. Length: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters.
5. Content: Be direct, try to eliminate filler words and phrases in these sentences (examples: though, maybe, I think, kind of). Think like a journalist.

How to Find Your Inner Journalist

I never quite thought my Journalism minor would benefit my future career as a Software Engineer, but here we are!

Journalists and writers ask themselves questions to ensure their article is detailed, straightforward, and answers all of the reader's questions.

When writing an article they look to answer who, what, where, when, why and how. For committing purposes, it is most important to answer the what and why for our commit messages.

To come up with thoughtful commits, consider the following:

• Why have I made these changes?
• What effect have my changes made?
• Why was the change needed?
• What are the changes in reference to?

Assume the reader does not understand what the commit is addressing. They may not have access to the story addressing the detailed background of the change.

Don't expect the code to be self-explanatory. This is similar to the point above.

It might seem obvious to you, the programmer, if you're updating something like CSS styles since it is visual. You may have intimate knowledge on why these changes were needed at the time, but it's unlikely you will recall why you did that hundreds of pull requests later.

Make it clear why that change was made, and note if it may be crucial for the functionality or not.

See the differences below:

1. git commit -m 'Add margin'
2. git commit -m 'Add margin to nav items to prevent them from overlapping the logo'

It is clear which of these would be more useful to future readers.

Pretend you're writing an important newsworthy article. Give the headline that will sum up what happened and what is important. Then, provide further details in the body in an organized fashion.

In filmmaking, it is often quoted "show, don't tell" using visuals as the communication medium compared to a verbal explanation of what is happening.

In our case, "tell, don't [just] show" – though we have some visuals at our disposal such as the browser, most of the specifics come from reading the physical code.

If you're a VSCode user, download the Git Blame extension. This is a prime example of when useful commit messages are helpful to future developers.

This plugin will list the person who made the change, the date of the changes, as well as the commit message commented inline.

Imagine how useful this could be in troubleshooting a bug or back-tracing changes made. Other honorable mentions to see Git historical information are Git History and GitLens.

Conventional Commits

Now that we've covered basic commit structure of a good commit message, I'd like to introduce Conventional Commits to help provide some detail on creating solid commit messages.

At D2iQ, we use Conventional Commit which is a great practice among engineering teams. Conventional Commit is a formatting convention that provides a set of rules to formulate a consistent commit message structure like so:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit type can include the following:

• feat – a new feature is introduced with the changes
• fix – a bug fix has occurred
• chore – changes that do not relate to a fix or feature and don't modify src or test files (for example updating dependencies)
• refactor – refactored code that neither fixes a bug nor adds a feature
• docs – updates to documentation such as a the README or other markdown files
• style – changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.
• test – including new or correcting previous tests
• perf – performance improvements
• ci – continuous integration related
• build – changes that affect the build system or external dependencies
• revert – reverts a previous commit

The commit type subject line should be all lowercase with a character limit to encourage succinct descriptions.

The optional commit body should be used to provide further detail that cannot fit within the character limitations of the subject line description.

It is also a good location to utilize BREAKING CHANGE: <description> to note the reason for a breaking change within the commit.

The footer is also optional. We use the footer to link the JIRA story that would be closed with these changes for example: Closes D2IQ-<JIRA #> .

Full Conventional Commit Example

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz. 

BREAKING CHANGE
Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Closes D2IQ-12345

To ensure that these committing conventions remain consistent across developers, commit message linting can be configured before changes are able to be pushed up. Commitizen is a great tool to enforce standards, sync up semantic versioning, along with other helpful features.

To aid in adoption of these conventions, it's helpful to include guidelines for commits in a contributing or README markdown file within your projects.

Conventional Commit works particularly well with semantic versioning (learn more at SemVer.org) where commit types can update the appropriate version to release. You can also read more about Conventional Commits here.

Commit Message Comparisons

Review the following messages and see how many of the suggested guidelines they check off in each category.

Good

• feat: improve performance with lazy load implementation for images
• chore: update npm dependency to latest version
• Fix bug preventing users from submitting the subscribe form
• Update incorrect client phone number within footer body per client request

Bad

• fixed bug on landing page
• Changed style
• oops
• I think I fixed it this time?
• empty commit messages

Conclusion

Writing good commit messages is an extremely beneficial skill to develop, and it helps you communicate and collaborate with your team. Commits serve as an archive of changes. They can become an ancient manuscript to help us decipher the past, and make reasoned decisions in the future.

There is an existing set of agreed-upon standards we can follow, but as long as your team agrees upon a convention that is descriptive with future readers in mind, there will undoubtedly be long-term benefits.

In this article, we've learned some tactics to level up our commit messages. How do you think these techniques can improve your commits?

I hope you've learned something new, thanks for reading!

Connect with me on Twitter @ui_natalie.

Do you have a new software project on the horizon? You should prepare for success. The process of development determines the outcome. And a crucial part of making sure things run smoothly is having the right documentation in place.

Before you start designing, coding, building, and testing, take the time to prepare all the software documentation you need. It’s not the most exciting part of a software project, but it does make all the difference.

How important is documentation?

The software industry is one that is particularly fast-paced. To keep up, you might want to start developing as soon as you get a great idea. But hold your horses. Cutting corners won’t actually bring you further.

Time spent on documentation rather than developing is not lost. On the contrary, if it’s done right, it will not only save you time, but also improve your product. As a project scales, the documentation will serve as guidelines that will enable you to do things right on the first try. No guesswork or free-styling.

A project manager who has a great overview of the project in their head is great—but developers or new team members can't access that. Details can get lost in communication.

Technical documentation can make or break a project. If every step of the way for a project is well-documented, it can run smoothly and save time. No one-on-one conversations to give the right people the right information, and with that, no misunderstandings.

Why write project documentation?

Your project will depend less on individual people

With detailed documentation, onboarding new team members becomes a breeze. When your product is growing, changing, and scaling, you can easily refer new talent to the necessary documentation and have them up and running in no time.

This also works the other way around: if a team member leaves, they don’t take all their knowledge about the project with them. It’s still there in the documentation.

A project with great documentation simply relies less on the individuals working on it. It has its own framework that anyone should be able to work with. It makes your software project more resilient against unexpected challenges.

Communication with stakeholders and clients becomes easier

But the benefits of having a well-documented software project go beyond internal processes.

With the right documentation, it also becomes easier to present your product to stakeholders, making it more understandable what you’ll be creating. Anything that’s on paper is easier to review and understand than ideas in your head.

Documentation for your product helps in the pitching process, but also when you're further down the line. If a client has approved the documents you presented, it’s easy to fall back on them whenever an issue arises. No he-said-she-said: it’s all right there, ready to be referred to.

At the end of the day, a successful project isn’t only about the product you build—it’s also the relationships you built. Prevent any issues while you can and ensure a pleasant collaboration.

How to write good documentation

All of this doesn’t require encyclopedia-like documentation. Just make sure you cover the essentials for your project specifically. In this article, we’ll give you some advice on how to do that.

Make an inventory of what documents you will need

Do you have your whole project already planned out in your head? That’s a great start—but I’d still recommend that you document it. If you don’t see the sense of creating any documentation whatsoever for yourself, remember that you’re mainly doing it for the users of your end project.

They will notice: not only in how well the software tool works, but also in how fast it was delivered—without you having to make a lot of changes after launch.

But what kind of documents will you actually need? Depending on the size of the project, you could need documentation that will guide daily processes. Or maybe you mostly need a framework for the bigger picture.

Let’s divide software documentation into two categories: process and product documentation.

What is product documentation?

Product documentation describes the end goal: the actual product you are building. How it works, how to work with it, technological specifications, manuals–anything you need to know once the product exists.

For your developers, the most important product documentation is the system documentation. It explains how the software product works, why it works in a certain way, and how to work with it.

For the actual users of your software product, user documentation is essential. Think tutorials, FAQs for troubleshooting, and a manual that will help them use and love your product the way you intended.

What is process documentation?

See this as the roadmap that will bring your project from idea to existence. In this you can include:

• Test standards and schedules: making sure everyone tests your product in the same way, so the results will actually be relevant.
• Meeting notes: save them, so you can hand them over to your client whenever a disagreement arises.
• Project plans: how will you be building your product? What milestones do you want to reach along the way and when?

Determine crucial information

Within your process documentation, you can decide how detailed you’ll map out the steps and process. If you’re an experienced software developer or project manager, you will know what questions are likely to come up, and which discussions will arise.

If you’re new to this, you might be clueless as to what you can or should include. Here are some examples you might overlook or not think of that can fast-track your project development.

Data and privacy compliance

If it’s relevant to your product, create guidelines that will help your team stay in between the lines of what’s allowed regarding data regulations. What rules are in place? What process should employees follow so they know they’re safe?

Emergency plans

What do you do when your server goes offline? What’s the first step after a security breach? What if your hardware tomorrow decides it doesn't want to work anymore? Having answers to questions like these can save you a lot of time and money.

Visual documentation

Don’t worry designers, technical documentation is not just words. People are still mostly visual thinkers. That’s why diagrams can help you make workflows clearer.

But visuals that explain how the product should be working at the end of the project also contributes to a more streamlined way of working—especially if what you’re building is quite complex.

Still unsure what to include? Ask the people it will concern. Sit your team around the table and determine together what they want to have on paper to prevent issues down the line.

Write effective technical documents

Don’t worry, I’ll actually tell you how. Most people aren’t born writers–let alone born technical writers. Writing technical documents can seem like a boring and at the same time daunting task. After all, making a mistake in a technical document could have pretty big implications for the product or process. Making an error in a user manual could, too.

Watch your language

You don't need to impress anyone with a technical document. Your team members will know that you are knowledgeable, without you using jargon where it's simply not necessary.

Many people feel the need to write way more difficult language when it comes to business-related documents. But you’re still dealing with people, humans you speak to in a certain way. Try to use that way of speaking in your writing as well to make your documents more comprehensible.

Keep your sentences short. Simplify your words. Prevent misunderstandings.

The goal of technical documentation is to make things clearer and speed things up. Not to produce more questions. This applies even more so on documents that are meant for the end-user.

For bonus points, write different documentation based on different user personas. Take Python for instance, which has great documentation for a variety of different users from beginners to seasoned professionals.

Organize your thoughts

Yes, if you are planning to write a plan, you’ll need to have a plan for writing it. Having a clear structure in your technical documentation is what will save the readers and users time. Use headers. Find a chronological order.

If it’s your first rodeo, simply start with using a template for your technical document. You don’t have to reinvent the wheel.

Time to test

Let someone else read your technical documentation to make sure it’s easy to understand and covers all relevant aspects.

Too often, user manuals are just seen as a side-product and not included in the testing. Set yourself up for success by including it in your tests and development.

Do yourself a favor for future projects

Creating technical documentation doesn’t just benefit the project you’re working on now. It can also help future projects, as the framework is already there. Just make the necessary changes based on your product and past experience and you’re ready to start developing.

Everyone says you should learn Git—and you should—but let's be honest: Git is kind of hard.

Even almost ten years into my software development career, I am still learning about the underlying Git fundamentals and how to use Git more effectively.

It wasn't too long ago that I realized I had a fundamental misunderstanding of a key command I'd used countless times.

Like many other areas in programming, I believe the best way to learn is to just start doing.

Just start being productive with the tool—the fundamentals and edge cases will get sorted out over time.

So in this tutorial that's exactly what we'll do. We'll work through a series of examples to build a from-the-ground-up understanding of how to use Git and ultimately collaborate with your teammates.

In doing so, we'll use simple commands and explain the underlying concepts as they're useful—but only to the extent that they aid understanding.

There's definitely a lot more to Git than is presented here, but these are things you'll learn as you work with it over time.

I also will not be using any tree diagrams (like the one below) because they only confuse me, and I've never had to think about Git in this way to be productive as a software developer.

https://www.atlassian.com/git/tutorials/using-branches/git-checkout

Here's what we'll cover. Don't let this list intimidate you, we'll go step by step.

• Installing git and setting up a GitHub account
• How to create a new repository in GitHub
• Cloning the repository
• Git branches
• How the check the status of a Git project
• How to make our first commit
• How to push up our first commit to GitHub
• How to add another commit in Git
• How to stage changes in Git
• How to view the Git diff
• How to collaborate with others in Git
• Feature branches in Git
• Git workflows for collaboration
• How to merge a branch in Git
• Pull request workflow
• How to bring our local up to date
• How to retrieve remote data
• How to fix merge conflicts in Git
• Review: how to start a new feature workflow
• Conclusion

So with all of that said, I encourage you to follow along with the examples on your own machine—let's start!

How to install Git and set up a GitHub account

First, some boring stuff we need to do to get up and running.

If you already have Git installed, have made a GitHub account (or use any other provider like GitLab or Bitbucket), and you have setup an SSH key, you can skip this section.

If not, you'll first need to install Git.

Secondly, we'll be using GitHub in this tutorial, so signup for a GitHub account here.

After you have a GitHub account, you'll need to create an SSH key to push your code from your local machine to GitHub (this key proves to GitHub when you push code that you are "you").

It's not difficult—just follow the steps here.

How to create a new repository in GitHub

The next thing we'll do is create a new repository in Github.

It's simple. Just click the "New" repository button on your home page:

Creating a new repository

Next, choose a name for the repository and whether you want the repo to be public or private. You can optionally add a README file if you'd like, and then click "Create repository."

Configuring the new repo

I've called my repository practical-git-tutorial. This repo has all of the finished steps of this tutorial already in it, so if you want to you can always use it as a reference.

How to clone a Git repository

To start, we'll "clone" the repo. Cloning a repo means downloading all of the project's code and metadata from the source—which in this case is GitHub.

To clone a repo, we use git clone <URL>.

I used the URL from the repo I just created, but you should use the URL of your own repository:

$ git clone git@github.com:johnmosesman/practical-git-tutorial.git
Cloning into 'practical-git-tutorial'...
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 6 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (6/6), done.

Note: commands to be run in your terminal will be prefixed with a $.

We'll go into more detail about what git clone does soon, but for now just know that it downloads the project and places it in a folder in your current working directory.

Next let's change into the new directory using cd:

$ cd practical-git-tutorial/
/practical-git-tutorial (main)$

We've changed into the folder (which is just like any other folder), and your terminal may show you something alongside the directory name: (main).

Git branches

This (main) means that we are currently on a branch called main. You can think of a Git branch as a copy of the project at a specific point in time that can be changed independently of other branches.

For example, if we used Git to track writing a book, we might have branches that look like this:

• main branch
• table-of-contents branch
• chapter-1 branch
• chapter-2 branch
• etc.

The main branch is, well, the "main" branch—the place where we're going to combine all of the contents of the book into one finalized, finished book.

We can create other branches to separate and track specific pieces of work.

If I was working on Chapter 1 and you were working on Chapter 2, we could create two difference branches, chapter-1 and chapter-2—effectively two different copies of the current status of the book.

We could then both work on our respective chapters without stepping on each others' toes or changing the contents out from under each other—we both have our own working copy that are separate from each other.

When either of us are finished with our chapter, we can add the contents of our chapter branch back into the main branch. When we're both finished, the main branch will contain both Chapter 1 and Chapter 2.

However, there are times where you will overwrite or change the same piece of content as someone else and we'll have to figure out how to settle those differences—and we'll see that soon.

Note: depending on the project you may see a branch named master instead of main. It doesn't have any functional difference, just type master vs main depending on what's in your project.

How to check the status of a Git project

One thing we'll do often is check the status of our project. What changes have been made and what do we want to do with them?

To view the status of our project we use git status:

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

There's a few things in the result of this command, so let's break those down.

The first thing git status tells us is we're on the main branch:

 On branch main

The second sentence is a little more interesting:

Your branch is up to date with 'origin/main'.

Git is telling us that our branch is "up to date" with something called origin/main.

origin is a new concept known as a remote. A remote is a "remote source" different from your local machine.

In this project we have our local copy of the project, but we can also add remote sources that we can collaborate with. After all, that is one of the biggest benefits of Git: controlled collaboration with others.

Continuing with our book-writing example, if I write Chapter 1 on my machine and you write Chapter 2 on your machine, we could both add each other's computers as "remotes" and send and receive changes from each other.

In practice, the programming community at large has decided that it is best to have a single source of truth for code. One place that is always "correct" about what the current state of the codebase is. By convention, we call this place the origin.

In this case, GitHub is our "origin."

In fact, we can see this by running the command git remote -v (-v for "verbose"):

(main)$ git remote -v
origin  git@github.com:johnmosesman/practical-git-tutorial.git (fetch)
origin  git@github.com:johnmosesman/practical-git-tutorial.git (push)

This command lists all of our remotes. From the result we can see that we have a remote named origin, and the Git URL of this remote points to our repo on Github.com. This remote was automatically setup for us when we ran git clone.

So coming back to this statement in the result of git status:

Your branch is up to date with 'origin/main'.

When we asked for the status of our project, Git told us that our local main branch is up to date with the main branch at our origin—which is GitHub.

In fact, git clone automatically created a main branch for us locally because it saw that the origin we cloned from had a branch called main as its primary branch.

Basically, there are no changes on our local machine different from GitHub or vice versa—our local main branch and the GitHub main branch are identical.

As we make changes we'll see this message change to reflect the differences in our local repository and the origin (GitHub) repository.

The final message from git status is about the state of the local project:

nothing to commit, working tree clean

We'll go into more detail here as we make changes, but this message is basically saying we haven't done anything—so no changes to report.

To summarize the result of git status:

• We're on branch main
• Our local main branch is identical to the origin's (GitHub's) main branch
• We haven't made any changes to the project yet

How to make our first commit

Now that we understand the initial state of our project, let's make some changes and look at the result.

Continuing with our book analogy, let's make a new file called chapter-1.txt and insert a sentence into it.

(You can use the terminal commands below, or create and edit the file in any text editor you choose—it doesn't matter.)

(main)$ touch chapter-1.txt
(main)$ echo "Chapter 1 - The Beginning" >> chapter-1.txt
(main)$ cat chapter-1.txt
Chapter 1 - The Beginning

The commands above make a new file called chapter-1.txt using touch, insert the sentence "Chapter 1 - The Beginning" using echo and the >> operator, and, to double-check our work, show the contents of the file using cat.

The result is a simple text file with one sentence in it.

Let's run git status again and see the difference in its output:

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        chapter-1.txt

nothing added to commit but untracked files present (use "git add" to track)

Here we see a different output than before. We see a section describing "Untracked files," and our new file chapter-1.txt is listed there.

Before Git will start tracking changes to a file we first have to tell Git to track it—and as the bottom of the message states—we can use git add to do that:

(main)$ git add chapter-1.txt

(Instead of specifying the name of the file for git add, you can use a period (.) to add all of the changes in the directory.)

Let's check the status again:

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   chapter-1.txt

john:~/code/practical-git-tutorial (main)$

The message has changed again. It nows says that we have some changes that are ready to be "committed."

A commit in Git is a saved chunk of work, but it's a little different from the same save you would use to save a text file in a text editor.

You can think of a commit as a completed idea or unit of work.

For example, if we were continuing to write the contents of Chapter 1 in the book, it might look like this:

• Write the title of the chapter. click save in our editor
• Write the first paragraph of the chapter. click save in our editor
• Write the second paragraph of the chapter. click save again
• Write the final paragraph of the chapter. click save again

Here, we've "saved" the document four times, but at the end of those four saves we now have the first draft of our chapter, and that draft is one "unit of work."

We want to save this file on our computer, but we also want to signify that this is a unit of completed work—even if it's just a draft. It's a chunk of work worth holding onto. We may want to return to it in the future, go back and edit it, or merge this draft into the current draft of the entire book.

To do this, we create a new commit to signify this milestone. Each commit gets its own unique identifier, and the order of the commits are preserved.

To commit our changes, they must first be added to the staging area by using git add.

(We'll talk more about the staging area soon.)

Next, we need to finalize the commit by using git commit.

It's best practice to provide a detailed message of what changes you made—and more importantly—why you are committing these changes.

Once the commit history becomes hundreds or thousands of commits long, it becomes near impossible to understand why a change was made without a good commit message. Git will show us what files changed and what the changes were, but the meaning of those changes is up to us to provide.

Let's commit the new file we made with a commit message by using the -m or "message" flag:

(main)$ git commit -m "New chapter 1 file with chapter heading"
[main a8f8b95] New chapter 1 file with chapter heading
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-1.txt

We've now committed that chunk of work, and we can see that by viewing the Git log via git log:

(main)$ git log
commit a8f8b95f19105fe10ed144fead9cab84520181e3 (HEAD -> main)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Fri Mar 19 12:27:35 2021 -0500

    New chapter 1 file with chapter heading

commit 2592324fae9c615a96f856a0d8b8fe1d2d8439f8 (origin/main, origin/HEAD)
Author: John Mosesman <johnmosesman@users.noreply.github.com>
Date:   Wed Mar 17 08:48:25 2021 -0500

    Update README.md

commit 024ea223ee4055ae82ee31fc605bbd8a5a3673a0
Author: John Mosesman <johnmosesman@users.noreply.github.com>
Date:   Wed Mar 17 08:48:10 2021 -0500

    Initial commit

Looking at this log, we see that there are three commits in the project history.

The latest commit is the one we just made. We can see the same commit message we just used: "New chapter 1 file...".

There are also two previous commits: one when I initialized the project and another when I updated the README.md file on GitHub.

Notice that each commit has a long string of numbers and characters associated with it:

commit a8f8b95f19105fe10ed144fead9cab84520181e3 (HEAD -> main)

This string of characters and numbers is called the SHA—it's the unique ID generated by a hashing algorithm for this commit. Just take note of these for now—we'll come back to this soon.

We also see two other interesting things in the log after the commit SHAs:

• (HEAD -> main) next to our latest commit
• And (origin/main, origin/HEAD) next to the commit before that one.

This information tells us the current status of our branches and remotes (as far as we know—but more on this later).

For the latest commit, we see that the HEAD (aka "where we are now" in the project history) is pointing at our local main branch—represented by HEAD -> main.

This makes sense because we just made that commit, and we haven't done anything else—we're still at the point in time where we made that commit.

If we look at the previous commit starting with 25923, we see (origin/main, origin/HEAD). This tells us that, on the origin (aka GitHub), GitHub's HEAD or "current place" is on our previous commit.

Basically, our local machine thinks the latest change for local main branch is the commit where we added Chapter 1, and our local machine also thinks that on GitHub the latest change is the commit where I updated the README before I wrote this post.

And this makes sense—we haven't told GitHub about the newest commit we made. GitHub still thinks that the repo is up to date with what it has seen.

Now let's push up our new commit to GitHub.

How to push up our first commit to GitHub

We have a new commit on our local machine and we need to update our "source of truth"—the origin remote—aka GitHub.

We're currently on the main branch locally, so we need to tell GitHub to update its own main with the new commit that we made.

To do that we use the git push command and we can specify where we want to push and what branch we want to push to.

(main)$ git push origin main
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 16 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 326 bytes | 326.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To github.com:johnmosesman/practical-git-tutorial.git
   2592324..a8f8b95  main -> main

Here we pushed to the origin remote (GitHub) and to the main branch.

The output tells us about some file operations Git did to do that, and the last line of the output tells us which commits it pushed and to where:

To github.com:johnmosesman/practical-git-tutorial.git
   2592324..a8f8b95  main -> main

Here it shows us that we pushed our main branch to GitHub's main branch.

If we look back at the git log output we'll notice that both our local and origin point to the same commit now:

(main)$ git log
commit f5b6e2f18f742e2b851e38f52a969dd921f72d2f (HEAD -> main, origin/main, origin/HEAD)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:07:35 2021 -0500

    Added the intro line to chapter 1

In short, on origin (GitHub) the main branch (also written as origin/main) has now placed our new commit as the latest commit in the history.

If we were working with other collaborators, they could now pull down our newest change from GitHub and begin editing the Chapter 1 as well.

How to add another commit in Git

Before we start collaborating with others, let's make another small change to see what happens when we edit an existing file.

Let's add another line into our Chapter 1 file:

(main)$ echo "It was the best of times, it was the worst of times" >> chapter-1.txt
(main)$ cat chapter-1.txt
Chapter 1 - The Beginning
It was the best of times, it was the worst of times

Using cat we can see that our file now contains two lines.

Let's look at the status of our Git repo again:

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   chapter-1.txt

no changes added to commit (use "git add" and/or "git commit -a")

Starting from the top, we'll notice the output says Your branch is up to date with 'origin/main'.

This might seem odd to you since we just changed a file, but Git is only comparing the commits we've made against the commits in origin/main.

The next section of the output explains it a little more:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   chapter-1.txt

Here Git tells us that we have "changes not staged for commit."

Before we can commit a set of changes, we first have to stage them.

How to stage changes in Git

To illustrate the usefulness of the staging area, let's first stage our changes by using git add:

(main)$ git add .
(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   chapter-1.txt

These changes are now ready to be committed, but before we commit them let's add another change into our chapter-1.txt file.

I'm going to replace the contents of chapter-1.txt entirely with new text:

Note: I'm using > here instead of >> which will replace the contents of the file instead of appending to the file.

(main)$ echo "New file contents" > chapter-1.txt

(main)$ cat chapter-1.txt
New file contents

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   chapter-1.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   chapter-1.txt

From the output we can see that we now have staged changes, and not staged changes.

While the file itself can only contain one thing, Git keeps track of both changes for us—even though they're changes to the same lines!

However, from the output above we can't really tell what those changes were—we just know that they exist.

To view these changes, we'll first look at the command line way (which I never use), and then a way that uses a GUI (which is 100% nicer).

How to view the Git diff

To view the changes, we need to look at the Git diff.

A diff (short for difference) is the difference between two sets of changes. Those changes could be anything from staged changes to not-staged changes to commits.

The command line way to do this is by using git diff.

We'll look at this output in our simple case here just for completeness' sake. But, as I mentioned before, we're interested in effective Git workflows, and once you get to changes of any decent size across multiple files this command line output just becomes not effective.

But for completeness, here it is:

(main)$ git diff
diff --git a/chapter-1.txt b/chapter-1.txt
index 0450d87..4cbeaee 100644
--- a/chapter-1.txt
+++ b/chapter-1.txt
@@ -1,2 +1 @@
-Chapter 1 - The Beginning
-It was the best of times, it was the worst of times
+New file contents

My terminal attempts to colorize this output to help with readability, but the important parts to notice here is it tells us what file we're diffing, chapter-1.txt, and at the bottom it shows us the actual differences. Let's key in on those lines:

-Chapter 1 - The Beginning
-It was the best of times, it was the worst of times
+New file contents

The lines starting with a minus sign (-) are lines we deleted entirely or in part, and the lines starting with a + sign represent lines added entirely or in part.

Now, with multiple files and many lines changed this output becomes unwieldy—fast. There is a better way, and even almost ten years into my programming career I still use a simple GUI program to help look at and manage diffs.

The program I use is called GitX, and it's an old and outdated piece of software that's not even really being maintained anymore. However, I just use it to view and manage file diffs—so it works for me.

I wouldn't particularly recommend this one, but it is free. Although I've never used it, the GitHub Desktop client is probably a good choice.

Now with that little aside out of the way, here's what the diff looks like in my tool.

To start, the staged changes on the right-hand side show our original add of the second sentence:

Staged changes in GitX

In the unstaged changes on the left-hand side, we see the removal of those two lines entirely and the addition of a new line:

Unstaged changes in GitX

This corresponds to the file replace command we ran.

It is so much easier to understand the diff in a GUI program. This program also allows me to quickly switch between staging and un-staging files by just dragging them around. I can even stage or un-stage individual lines in a file back and forth as well.

There's no bonus points for using the command line vs a GUI program. Use whatever gets the job done for you.

Now that we've seen how the staging area and Git diffs work, let's discard our non-staged changes so we can get back to committing our first change.

In my GUI program I can right-click the file and click "Discard changes", but I'll show the command line version here as well.

The output of our last git status actually showed us how to do this by using git restore. We can pass the file path or just a . for the whole directory:

(main)$ git restore .

If we check the status again we're back to just our staged changes, and we can continue.

Note: Git only commits changes that are staged, so we could have left those unstaged changes in our working directory and it wouldn't interfere with the committing process.

However, it would make our future changes more cumbersome to deal with—so it makes sense to discard those changes to keep our working directory in good shape.

Now let's finally commit these changes with a message about what we did:

(main)$ git commit -m "Added the intro line to chapter 1"
[main f5b6e2f] Added the intro line to chapter 1
 1 file changed, 1 insertion(+)

Checking the status once again shows us that our branch is "ahead of 'origin/main' by 1 commit":

(main)$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

Finally let's push up our change:

(main)$ git push origin main

How to collaborate with others in Git

So far we've been looking at the simplest use case: working by ourselves on one branch.

In reality, we'll usually be working with multiple people working on multiple different branches. This is the real power of Git after all: a system to collaborate and track changes over time amongst many collaborators.

For now, let's continue working as if we're the only person on the project, but let's adjust our workflow a little bit to prepare for when that's not the case.

In general, it's best practice to not work directly on the main branch.

The main branch is supposed to be the "source of truth" for the project—changes to it should be carefully reviewed. Any change in origin/main becomes the new "source of truth" for anyone else working on the project, so we shouldn't just change it without some thought and review by others.

Instead of working on main directly, let's branch off of main into our own feature branch, and then merge those changes back into main.

That's a lot of new terminology, so let's take it one step at a time.

Feature branches in Git

To begin, let's branch off of main and create our own feature branch to work on.

When you create a branch off of another branch, you create a copy of that branch at that point in time. You can now change this new branch independently of the original branch.

To try this out, let's make a new branch called chapter-2. To do this we use git checkout with the -b flag and the name we want the new branch to have:

(main)$ git checkout -b chapter-2
Switched to a new branch 'chapter-2'
(chapter-2)$

Notice that the terminal now shows us on the chapter-2 branch. Changes on the chapter-2 branch will not affect the main branch at all. We essentially have a new playground to make whatever changes we want to make without affecting main.

There are interesting things happening under the hood here, but for the purpose of this tutorial we just need to know that to "checkout" something in Git means to "change my local project to look exactly like the project looked at some specific point in time." You can think of a branch as a pointer to a specific timeline of the Git history.

There's a lot more happening here, but that definition should be good enough for now.

So we have a new branch, and for now that new branch is identical to main (we haven't made any changes yet).

Next let's repeat what we've already done before and create a new file called chapter-2.txt, give it some content, and commit it:

(chapter-2)$ touch chapter-2.txt
(chapter-2)$ echo "Chapter 2 - The next chapter" >> chapter-2.txt

(chapter-2)$ git status
On branch chapter-2
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        chapter-2.txt

nothing added to commit but untracked files present (use "git add" to track)

(chapter-2)$ git add .

(chapter-2)$ git commit -m "Creates chapter 2 and adds the topic sentence"
[chapter-2 741822a] Creates chapter 2 and adds the topic sentence
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-2.txt

Nothing new in there—just the same thing we did for Chapter 1.

Now that we have a new commit on our chapter-2 branch, let's look the Git log and compare this new branch to main:

(chapter-2)$ git log
commit 741822a9fd7b15b6e3caf437dd0617fabf918449 (HEAD -> chapter-2)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:33:26 2021 -0500

    Creates chapter 2 and adds the topic sentence

commit f5b6e2f18f742e2b851e38f52a969dd921f72d2f (origin/main, origin/HEAD, main)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:07:35 2021 -0500

    Added the intro line to chapter 1

commit a8f8b95f19105fe10ed144fead9cab84520181e3
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Fri Mar 19 12:27:35 2021 -0500

    New chapter 1 file with chapter heading
...

We'll notice in the log that our latest commit is shown at the top, and our HEAD is again different from our origin. This again makes sense—we've made changes locally that aren't in GitHub.

Now we need to get our new changes into the main branch.

Git workflows for collaboration

There are a couple of ways to get our new Chapter 2 into the main branch and into GitHub, and the way we choose depends on the project and what workflow we're using to collaborate with others.

First let's talk about a couple different workflows we could use.

The first one is the most straightforward:

1. Merge changes from chapter-2 into our local main branch
2. Push local main branch to origin/main

The second way is a little more complicated:

• Push our local chapter-2 branch to origin (this creates a new branch on origin called origin/chapter-2)
• Merge origin/chapter-2 into origin/main on GitHub
• Pull down the new changes from origin/main into our local main

The first workflow is definitely easier, and it is something I would use if I was working on this project by myself without any other collaborators.

However, if I had collaborators, I wouldn't want to push directly to the main branch from my local. By doing so I would be changing and taking control of the history of the project solely on my own changes—without any input or review from collaborators.

For this reason, if there were multiple people working on the same project, I would use the second workflow because it is a better collaboration process for the team.

That being said, we'll go over both workflows, and let's start with the first one which is less complicated.

How to merge a branch in Git

When you want to combine the contents of two branches into one in Git, there are a few methods of doing so. The first and probably simplest way is to do a merge.

A merge, like it sounds, tries to take the contents of one branch and apply (or "merge in") those changes into another branch.

In our scenario, we want to take the contents of the chapter-2 branch and merge them into main. Said another way, we want to take the current state of main and add in our changes from the chapter-2 branch.

We can do this by using git merge, and we'll look at the result of it afterwards.

The first thing we need to do is be on the primary branch that we want to merge changes into. Since we want main to absorb the changes from chapter-2, we first need to be on the main branch.

To switch back to the main branch, we can again use git checkout and specify the branch name of main. This time we don't use the -b flag because we want to switch to an existing branch and not create a new one:

(chapter-2)$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
(main)$

We're now back on the main branch, and we get a quick status message saying we're up to date with origin/main.

Next, let's merge our chapter-2 branch into main:

(main)$ git merge chapter-2
Updating f5b6e2f..741822a
Fast-forward
 chapter-2.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-2.txt

Let's look at the Git log again to see the result:

(main)$ git log
commit 741822a9fd7b15b6e3caf437dd0617fabf918449 (HEAD -> main, chapter-2)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:33:26 2021 -0500

    Creates chapter 2 and adds the topic sentence

commit f5b6e2f18f742e2b851e38f52a969dd921f72d2f (origin/main, origin/HEAD)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:07:35 2021 -0500

    Added the intro line to chapter 1

...

We can see that our main branch now contains the new commit from chapter-2, and that our origin is still at the previous commit (as we haven't updated origin yet).

Finally, let's push our changes up to origin/main:

(main)$ git push origin main
Total 0 (delta 0), reused 0 (delta 0)
To github.com:johnmosesman/practical-git-tutorial.git
   f5b6e2f..741822a  main -> main

We've successfully merge our chapter-2 branch, and pushed that change up to GitHub!

As a final cleanup step, let's delete the chapter-2 feature branch as it has already been merged into main:

(main)$ git branch -d chapter-2
Deleted branch chapter-2 (was 741822a).

Note: the git branch command without a branch name argument will list all of the branches you have locally.

Adding the -d flag and a branch name deletes the branch passed in.

Pull request workflow

To work through our collaboration workflow, let's repeat the same thing we've done with Chapter 1 & 2 on a new branch called chapter-3:

(Now would be a good time to try this on your own!)

(main)$ git checkout -b chapter-3
(chapter-3)$ touch chapter-3.txt
(chapter-3)$ echo "Chapter 3 - The End?" >> chapter-3.txt
(chapter-3)$ git add .
(chapter-3)$ git commit -m "Adds Chapter 3"

Now we have a new commit on a new branch called chapter-3.

Let's review how we're going to get this new branch merged into main without acting directly on main ourselves:

• Push our local chapter-3 branch to origin (this creates a new branch on origin called origin/chapter-3)
• Merge origin/chapter-3 into origin/main on GitHub
• Pull down the new changes from origin/main into our local main

A couple more steps—but none that are too complicated.

The first step is to push our new branch to GitHub. Since this branch doesn't exist yet on GitHub, GitHub will make a new branch for us that is a copy of what we pushed:

(chapter-3)$ git push origin chapter-3
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 16 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 299 bytes | 299.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote:
remote: Create a pull request for 'chapter-3' on GitHub by visiting:
remote:      https://github.com/johnmosesman/practical-git-tutorial/pull/new/chapter-3
remote:
To github.com:johnmosesman/practical-git-tutorial.git
 * [new branch]      chapter-3 -> chapter-3

Now that we have our branch on GitHub, we can create a pull request to be reviewed by our teammates.

GitHub even provides us with the URL to visit in our output above: https://github.com/johnmosesman/practical-git-tutorial/pull/new/chapter-3

A couple notes: this next part shows GitHub's UI and process for pull requests, but this process should be very similar for other services (like GitLab, Bitbucket, etc.).

Also keep in mind I'm using my own repo, so some of the URLs you see here will be different from yours.

Visiting the URL above, we arrive at a page to open a new pull request.

We see a few things:

• A place to specify the name of the pull request (a topic sentence to easily understand what this PR is about)
• A box for a description to explain the changes we made and any other context we want to provide (you can also add images, gifs, or videos here as well)
• And below all of that is the list of files we changed and the changes in them (the diff).

Opening a new pull request

Notice that the UI shows base: main <- compare: chapter-3. This is GitHub telling us that we're setting the pull request to merge chapter-3 into main.

Below the pull request description is the diff of the changes we made:

The pull request diff

We'll notice that only the file chapter-3.txt is shown, and this is because it's the only file that we changed.

There are other files currently in our project (chapter-1.txt, chapter-2.txt), but those files didn't change so there's no need to show them.

We see the one line we inserted into chapter-3.txt—signified by a + sign at the start of the line and the green background which signifies an addition to the file.

After clicking "Create Pull Request" we're taken to the new PR we just made.

At this point we could assign a reviewer to the PR and have a back-and-forth discussion around the code by leaving comments on specific lines in the diff. After the code has been reviewed and we make any changes that need to be made, we're ready to merge.

For this sake of this tutorial we'll skip the review process, and just click the big green merge button:

Merged pull request

And with that, our pull request has been merged into main!

How to bring our local up to date

We've now made a change to origin/main in a safe, controlled, and peer-reviewed way.

But, our local doesn't know anything about this change. Locally, Git still thinks we're on our chapter-3 branch which isn't merged into main:

(chapter-3)$ git log
commit 085ca1ce2d0010fdaa1c0ffc23ff880091ce1692 (HEAD -> chapter-3, origin/chapter-3)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Tue Mar 23 09:19:14 2021 -0500

    Adds Chapter 3

commit 741822a9fd7b15b6e3caf437dd0617fabf918449 (origin/main, origin/HEAD, main)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:33:26 2021 -0500

    Creates chapter 2 and adds the topic sentence

...

Our local shows origin/main on the previous commit starting with 741822. We need to pull in the new information from our origin to update our local repository.

How to retrieve remote data

As with many other things with Git, there are many different methods to accomplish the same task.

For our purposes, we'll look at a straightforward way that will work in the majority of cases.

To start, let's switch back to our main branch locally:

(chapter-3)$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

Our local thinks we're up to date with origin/main because we haven't asked the remote repository (origin) for new information since we pulled the project at the beginning using git clone.

Git repositories are not live-updating—they're just a snapshot of the history at a point in time. To receive any new information about the repository we have to ask for it again.

To retrieve any new information that has changed on the remote, we use git fetch:

(main)$ git fetch
From github.com:johnmosesman/practical-git-tutorial
   741822a..10630f2  main       -> origin/main

The output shows us that origin/main is now pointing to a commit starting with 10630f2. This commit prefix matches the SHA of the merge commit of our pull request.

There are a few ways to merge two branches into one another, and one of those ways is by creating a merge commit. That's what happened here.

The merge commit of our PR

Our local repository now knows about the presence of these new commits, but we haven't done anything with them yet.

Running git fetch doesn't actually change any of our files—it just downloads new information from the remote about the status of the repo.

Now that our local repository is aware of the status of each branch (but hasn't changed or updated any of the branches), let's check our status again:

(main)$ git status
Your branch is behind 'origin/main' by 2 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)

Our local now knows that our local main is behind origin/main by 2 commits (the commit from the chapter-3 branch and the PR merge commit).

It also gives us the hint to use git pull to update our local branch:

john:~/code/practical-git-tutorial (main)$ git pull origin main
From github.com:johnmosesman/practical-git-tutorial
 * branch            main       -> FETCH_HEAD
Updating 741822a..10630f2
Fast-forward
 chapter-3.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-3.txt

The git pull command is actually a shorthand for running two commands: git fetch followed by a git merge.

Since git fetch doesn't apply any changes locally, it can be useful to use git fetch to see if our branches are up to date with the remote (maybe we don't want to merge in the changes yet), or to pull down new branches that exist on the remote and not on our local machine.

Fetching a new branch from a remote will go ahead and download that branch as well to your local machine—since it's a new branch it won't conflict with anything in your local setup.

We could have just done a git pull initially instead of first doing a git fetch, but I wanted to explain git fetch as it is useful in its own right.

After running git pull, if we run git status once again we'll see that everything is up to date.

And with that, we've pulled in changes from our remote and got our local up to date!

How to fix merge conflicts in Git

The final topic we'll cover is how to deal with conflicts.

So far, Git has just magically handled all of the file updating, and most of the time Git can just handle it. But, there are times when Git doesn't know how to combine changes together, and that creates a conflict.

A conflict occurs when merging two changes that have changed the same line in a file. If two commits have changed the same line in a file, Git doesn't know which commit's changes to use, and it will require you to make the choice.

To setup this scenario, I've created another branch on Github called chapter-3-collaboration. Let's imagine that a teammate has already started working on this branch and they've asked you to collaborate with them in finishing out Chapter 3.

Since this is a new branch that we don't have locally, we can use git fetch to retrieve the new branch information from the remote, and then switch to that branch using git checkout:

(main)$ git fetch
From github.com:johnmosesman/practical-git-tutorial
 * [new branch]      chapter-3-collaboration -> origin/chapter-3-collaboration

(main)$ git checkout chapter-3-collaboration
Branch 'chapter-3-collaboration' set up to track remote branch 'chapter-3-collaboration' from 'origin'.
Switched to a new branch 'chapter-3-collaboration'
(chapter-3-collaboration)$

We've now pulled down the new branch to our local repository and switched to it. This is the contents of chapter-3.txt on this new branch currently:

(chapter-3-collaboration)$ cat chapter-3.txt
Chapter 3 - The End?

This is a sentence.

It's a title and one sentence. Let's change the title to something new like "Chapter 3 - The End Is Only The Beginning."

The contents of chapter-3.txt now look like this:

(chapter-3-collaboration)$ cat chapter-3.txt
Chapter 3 - The End Is Only The Beginning

This is a sentence.

After committing that change, if we try to push it up we get this message:

(chapter-3-collaboration)$ git push origin chapter-3-collaboration
To github.com:johnmosesman/practical-git-tutorial.git
 ! [rejected]        chapter-3-collaboration -> chapter-3-collaboration (non-fast-forward)
error: failed to push some refs to 'git@github.com:johnmosesman/practical-git-tutorial.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Our teammate has already made some commits before we did, and pushed it to the remote branch. Our local branch is now out of date with the remote, and GitHub is denying our push until we merge in the changes from our teammate:

... the tip of your current branch is behind its remote counterpart. Integrate the remote changes ... before pushing again.

It also gives us a hint about how to do that: git pull.

(chapter-3-collaboration)$ git pull origin chapter-3-collaboration
From github.com:johnmosesman/practical-git-tutorial
 * branch            chapter-3-collaboration -> FETCH_HEAD
Auto-merging chapter-3.txt
CONFLICT (content): Merge conflict in chapter-3.txt
Automatic merge failed; fix conflicts and then commit the result.

After pulling—and as we might have expected given the topic we're currently discussing—we have a merge conflict.

Git tried to automatically merge our teammate's changes into ours, but there was a place in the file that it couldn't automatically merge—we both changed the same line.

Git stopped "mid-merge" and is telling us we need to fix the merge conflicts before it can finish the merge. Let's look at our git status currently:

(chapter-3-collaboration)$ git status
On branch chapter-3-collaboration
Your branch and 'origin/chapter-3-collaboration' have diverged,
and have 1 and 1 different commits each, respectively.
  (use "git pull" to merge the remote branch into yours)

You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
        both modified:   chapter-3.txt

no changes added to commit (use "git add" and/or "git commit -a")

Git tells us our branch and the remote branch have 1 commit different from each other. It also tells us that we have some "unmerged paths"—that we're currently mid-merge and we need to fix the conflicts.

It shows us chapter-3.txt is currently modified, so let's look at the contents of chapter-3.txt:

(chapter-3-collaboration)$ cat chapter-3.txt
<<<<<<< HEAD
Chapter 3 - The End Is Only The Beginning
=======
Chapter 3 - The End But Not The Ending
>>>>>>> 2f6874f650a6a9d2b7ccefa7c9618deb1d45541e

This is a sentence.

Git has added some markers to the file to show us where the conflict happened. Both we and our teammate changed the title sentence, so it's surrounded by Git's markers of a conflict: <<< and >>> arrows separated by a line of ===.

The top line, signified by <<<<<<< HEAD and followed by "Chapter 3 - The End Is Only The Beginning", is the change that we just made. Git is telling us that this line is where our current HEAD is at—i.e., this is the change at our current commit.

The line below it, "Chapter 3 - The End But Not The Ending" followed by >>>>>>> 2f6874f650a6a9d2b7ccefa7c9618deb1d45541e, is the line and commit from our teammate.

Basically, Git is telling us, "Which one of these lines (or some combination of these lines) do you want to keep?"

Notice that the line at the bottom file isn't wrapped up in the conflicts—it wasn't changed by both commits.

We need to resolve the conflict by deleting one of the lines or combining the two lines into one (and remember to remove all of the extra markers that Git put in there as well).

I'm going to take a combination of these lines, so the final file looks like this:

(chapter-3-collaboration)$ cat chapter-3.txt
Chapter 3 - The End Is Not The Ending--But Only The Beginning

This is a sentence.

To finish the merge, we just need to commit our conflict resolution:

(chapter-3-collaboration)$ git add .
(chapter-3-collaboration)$ git commit -m "Merge new title from teammate"
[chapter-3-collaboration bd621aa] Merge new title from teammate

(chapter-3-collaboration)$ git status
On branch chapter-3-collaboration
Your branch is ahead of 'origin/chapter-3-collaboration' by 2 commits.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

The result of git status tells us that our local branch is is ahead of 'origin/chapter-3-collaboration' by 2 commits..

Looking at the git log confirms this:

commit bd621aa0e491a291af409283f5fd1f68407b94e0 (HEAD -> chapter-3-collaboration)
Merge: 74ed9b0 2f6874f
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Thu Mar 25 09:20:42 2021 -0500

    Merge new title from teammate

commit 74ed9b0d0d9154c912e1f194f04dbd6abea602e6
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Thu Mar 25 09:02:03 2021 -0500

    New title

commit 2f6874f650a6a9d2b7ccefa7c9618deb1d45541e (origin/chapter-3-collaboration)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Thu Mar 25 08:58:58 2021 -0500

    Update title

...

The resulting commit history has both of the commits on the branch and our merge commit at the top.

From here, we just need to push up our changes to the remote:

(chapter-3-collaboration)$ git push origin chapter-3-collaboration
Enumerating objects: 10, done.
Counting objects: 100% (10/10), done.
Delta compression using up to 16 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 647 bytes | 647.00 KiB/s, done.
Total 6 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 1 local object.
To github.com:johnmosesman/practical-git-tutorial.git
   2f6874f..bd621aa  chapter-3-collaboration -> chapter-3-collaboration

Now that we've changed the remote branch, our teammate would need to do a git pull to merge in our new merged changes.

And, ideally we would tell our teammate that we pushed up a new change so they could pull it down before they continue editing—reducing the likelihood they'll have to fix a merge conflict in the future, too.

Branches off of branches

We could have also created our own branch off of the chapter-3-collaboration branch. This would let us work without having to worry about merge conflicts until the very end.

Once we had finished our work in our own separate branch, we could then merge our feature branch into our teammate's feature branch—and then into main.

chapter-3-collaboration-john -> chapter-3-collaboration -> main

As you can see the branch structure can get quite complicated as more and more branches branch off of each other and become ahead of and behind each other.

Because of this, it's generally a good idea to keep branches small and isolated and try to merge them quickly and often.

This can help avoid a lot of painful merge conflicts.

Review: how to start a new feature workflow

I'll end with a quick review of how to approach starting a new task and the commands and flows to do it.

Say you've been given your first ticket at a new job: a small bug to squash in your team's product.

The first thing you'd need to do is pull down the repo using git clone <URL>.

Next, you'd want to make a feature branch off of main using git checkout -b <BRANCH_NAME>. After that, you'd fix the bug and commit the change(s) using git add and git commit.

Maybe solving this problem takes multiple commits—or maybe you make a few commits in an attempt to solve it before you finally arrive at the solution. That's ok too.

After committing, you push your new branch to the origin (git push origin <BRANCH_NAME>) and create a pull request. After a code review your branch is merged in (yay!).

You've now completed your feature, and it's time to switch back to main (using git checkout main), use git pull to get your latest changes plus any other changes other people have made, and start off again with a new branch.

Conclusion

As mentioned in the beginning, there are many ways to approach working with Git and Git workflows.

There's also a lot of underlying Git "magic" (that is, code being run that you don't understand yet), but you will learn and pick up more of this with time.

I spent the first many years of my career just using memorized commands and workflows. It worked. As I ran into problems or collaborated with teammates I learned more and eventually my skill with Git expanded.

In the beginning, don't make it any harder than it has to be! You will learn over time.

If you liked this article, I write about technical topics like this as well as non-technical topics on my site.

I also write similar things on Twitter: @johnmosesman.

Either way, feel free to send me a message.

Thanks for reading!

John

This is a story about my team’s hard work developing not a single eCommerce platform, but a reusable one for different owners. We kept the same codebase, look, and feel, and made it highly customizable.

I will conclude with what we learned from the process. I think our takeaways will be a useful learning resource for other software developers out there (and for ourselves in future projects, as well).

I will try to focus on the relevant parts as much as possible to make it easier to understand. Having said this, a bit of background is needed to go through this article.

Table of Contents

• Context of the project
• The first MVP
• Implementing GraphQL
• Architecture and Tech Stack
• The second MVP
• Conclusion and lessons learned
• Final thoughts

Context of the project

The client we were developing the platform for was an eLearning company which was composed of 3 main sub-companies.

For the past few years, the sub-companies had been operating mostly independently. But now they were trying to create a standardized way of doing things, so they could grow together in the best way.

The project was an ambitious one. Creating an ecommerce platform that would work for all the sub-companies wasn’t easy to design or to implement. There were a large number of unsolved questions they had, which made it very hard to estimate.

The first MVP

To tackle this difficult challenge, we started from the bottom with one of the 3 sub-companies – let’s call it sub-company H. In fact, it wasn’t one of the main sub-companies, it was a sub-company from a sub-company.

To explain it better, if we name the 3 main sub-companies L, N, and P, then H was a sub-company of N.

Being a sub-sub-company didn’t mean the platform would be simpler to develop. It was quite the opposite, actually, given all the features proposed for the MVP.

Main company structure

While the main goal was for a user to be able to purchase a product (seems quite obvious), there were too many dependencies with other services to accomplish this seemingly simple MVP.

Part of the product and order information came from another team’s domain, the Integrations team (I will call it team In). They communicated with Swell and Klopotek, an ecommerce system where we stored the product's information along with the order’s status.

The discounts were also provided by team In’s, to which we had to subscribe and then calculate the final product price according to the user info and privileges before displaying it.

To make product content like images or descriptions accessible and customizable for the client we retrieved it through Contentful, a content platform where clients were able to manage it in an easy way.

We managed the payment with Stripe, a payments service, and then we communicated with team In to update the order status on Swell.

The service available for the user to authenticate should be agnostic to the owner and reusable on all sub-companies. It had to be provided by another team, yet in the end, we actually developed it ourselves.

And to put the icing on the cake, we also had to implement the user tracking with Segment, a popular service to collect user events from web and mobile apps.

Here is a simple diagram of what I have been describing which might make it easier to understand. I have grouped the microservices architecture in just Backend and Frontend to keep it simple.

MVP Architecture overview

Why We Chose GraphQL

To accomplish our goals for the project, we had to provide the frontend with a unique source of truth of the product’s core information from the backend.

Therefore the only thing that we aimed to have different from one store’s frontend to another would be the designs and the content from Contentful.

Regarding these designs and their implementations on React, we planned to use a shared-components-library.

Therefore, what is GraphQL doing here and why did we decide to go for it?

Well, in case you don’t know how GraphQL works, essentially it lets you define a Schema with all the properties and queries that could be made to your product. Then it lets you serve it to the frontend to let it decide what to request without the backend having to create an endpoint for each of those requests (like in REST services).

To learn more about it, check out this tutorial I wrote to explain it. It teaches you how to use it with Node.js. Also, their docs are worth checking out.

This meant that each of the shops would request the data they needed from the product just by looking at the Schema, the source of truth.

Thanks to this fact we would not have to implement different sources of data in the backend for each shop. This gave the frontend the power and responsibility (the first involves the second 🕷) to request the product data needed to display at each interface.

With great power comes great responsibility. — Stan Lee

Just to be clear, if we had decided to go with REST we would have needed to create different endpoints for each of the shops. Or we would have had to make the frontend retrieve all the product data in each shop and then decide which properties to display. This means it would've had to store unnecessary data in the frontend that would only add noise.

Or even worse, we would have had all the shops’ backend services deployed for each one of the frontend shops. This would've used unnecessary resources and increased the cost considerably.

Here is why we took this initial approach. The worst part, in my opinion, would've been the waste of time from maintaining and hardly refactoring all the mess that we would have created.

Furthermore, by making a single request on-demand, the payload was lighter, and therefore, the performance over the network was improved.

Anyway, as with every problem, there were other approaches we could've taken on the way to developing this project and its architecture. But at that moment this one seemed to us the best one.

Architecture and Tech Stack

The microservices architecture mainly consisted of Node.js services hosted on Azure K8s clusters. Depending on their needs and the data they worked with, they did or didn't have a MongoDB, PostgreSQL, or Redis database associated.

The asynchronous communication between them was handled mainly with Azure Service Bus topics and subscriptions through a publish/subscribe messaging communication model.

The main difference with common messaging queues is that you can have more than one receiver, so you do not have multiple queues to receive messages in more than one service.

Azure Service Bus messaging Queues. Source

Azure Service Bus messaging Topics. Source

On the frontend part, the sites were developed with React. Sometimes we used Next, and other ones we built from scratch with Create React App, depending on the complexity and the requirements of each.

We moved from Redux, used in previous projects, to the official Context API to manage most of the state.

Here are the main services and their functionalities for the first MVP architecture:

• shop-web-app: The client shop application.
• gateway-api-service: Proxy service to receive requests from the client and redirect them to the corresponding services.
• cms-api-service: Service to retrieve and serve the content from Contentful
• catalog-api-service: Service that subscribes to team In messages and persists the product core data to serve it later through GraphQL.
• orders-api-service. Service that handles all the payment business logic
• auth-api-service: Provisional service to implement the user authentication to be able to buy products.
• auth-web-app: The client for the auth service.
• integrations-ecommerce-api-service: service from the integrations domain that handles the payments. Although this service was not in our domain we developed it together to increase the delivery speed and free them from extra work.

First MVP architecture

To deploy and update the resources needed on Azure we used Terraform, which let us define infrastructure as code and manage their life cycles on the K8s clusters. We also worked with Azure DevOps as our CI & CD system.

On the services, we used Systemic, a Node.js framework for minimal dependency injection that lets you create components and their dependencies in a system. Each component handles a separate object from the domain such as the routing, controller, services, database, and so on in an agnostic way from the others.

Apollo was our choice to implement GraphQL. It provided us with a data graph layer to easily connect both frontend and backend.

Again, to learn more about it check out their docs or this tutorial.

Finally, we hosted the code on GitHub to make use of features like Pull Requests to review our code properly before implementing it.

The second MVP

An MVP (Minimum Viable Product) is the first prototype you create and deliver in a project. This means that there is usually just one, and when you create it you start implementing new features on it.

So, why did we focus on a second MVP for the same project? Well, when we reached a “stable” version of the first one, the client realized that we needed to start with the main sub-company stores. They decided to stop the sub-sub-company H store development to focus on the development of the new ones.

This was mainly because to some services ended their support for the sub-companies in the coming months, meaning that their stores had to be developed first.

Graphical representation of how we felt with the second MVP

Although we tried to make a proper estimation for the first MVP, we surpassed its deadline since some unplanned issues appeared along the way. Thus, when we were told that the new deadline would be even sooner, we decided to take a different approach to reach it on time.

We decided to develop more than one store at the same time, which was a double-edged sword approach.

On one hand, we would see on the go how well the reusability aspect of our platform worked while refactoring it. We would also end up with more than one store in the end.

On the other hand, we would have to set up and maintain the environments and resources of multiple shops. Plus we would have to implement their designs which would slow us down, meaning we might not reach the deadline on time, again.

We saw this MVP as an opportunity to start over and improve our codebase. So we added TypesScript and Styled-Components to our React application.

I have to admit that I was very happy when we made these choices because I had been working with that stack on my own projects. So now I was able to learn more and get even better at it.

Fortunateluy, we were able to reuse most of the code from the previous MVP for the React apps and the backend services. But not everything was a bed of roses.

Not all of us were used to working with this new stack and it slowed us down at the beginning. Furthermore, with the same stack, we started developing a React components library for all the platforms, which, even though it was planned for the first MVP, never saw the light.

By that time, the team in charge of the user authentication service started working on it so we stopped its development and just implemented it on the site.

In addition, we started the development of a products search service (search-api-service) with Azure Cognitive Search.

After all the changes mentioned above the architecture evolved this way.

Second MVP architecture

Conclusion and lessons learned

As I am writing this, the platform isn’t finished yet. But it has been a great challenge to get where we are.

We have learned some valuable lessons that can be useful to others, not just about the stack and architecture described above but about the way we worked as a team.

Innovate the stack

Working with new technologies can be risky and less comfortable than sticking with old and well-known ones. But innovation and adaptability is the right way to go so you don't get left behind in Software Development.

One of the most important points when you upgrade your stack or adopt a new one, apart from checking the proper way to do so following standards, is being sure the team is comfortable working with it,. Not just at the beginning, either, but during the whole process to make the transition easier.

Don’t underestimate, promise less, deliver more

We happily estimated the first MVP and agreed to deliver a great number of features. We ended up needing more time because of all the issues that appeared on the way and _had to learn to say “no” sometimes.

On the second MVP, we didn’t estimate that far ahead in time and didn’t commit ourselves to features we weren’t sure we could deliver within the time expected.

Because of this, we were able to work less stressed, have a better mood, deliver better code, and improve the client's feelings about the project since they weren’t disappointed with the progress.

Teamwork inside the team.

We realized that the best way to progress and develop was to feel comfortable – not just with the technologies but, most importantly, our teammates. Some of the measures that improved our relationship and teamwork were:

Team democracy.

No matter the work we were doing at the moment, all of us had the same voice and our opinion counted the same when making a choice. This was key when we discussed the adoption of the new stack and the practices we would follow.

Reviewing code.

Feedback is one of the best ways to improve not only the code itself but the way you write it too. That's why we decided to work with GitHub Pull Requests to implement most of the features.

Working with them not only improved our code base but also made us aware of how the features were being implemented in other areas, avoiding catchup meetings and helping us keep track of the full project scope.

We refined this system little by little with features like a minimum number of reviewers to merge them or subscribing to them through slack.

Helping and asking for help.

In my opinion, this one is a must. The team must lose the fear of asking for help if they get stuck. At the same time, they must be willing to help others when they ask for it.

I am happy to say that we were able to reach this balance and our work improved in many ways. The next point, pairing, was key in losing the fear of asking for help and getting to know each other better.

Pairing as much as possible.

At this point in software development, the advantages of doing pair programming are quite well known. We paired not just to deliver the features in a faster and better way of doing things, but to learn from each other's way of coding.

Each week, we decided the pairing tasks and teammates to implement them. But if someone needed or wanted to pair, we just asked for it and moments after a teammate offered to help.

Paying attention to feedback.

The sprint retrospectives were the perfect moment to review all the things that went well, those that went wrong, to propose changes, and to look forward to improvement. Therefore the more we shared our opinions the more issues we could approach and solve.

Teamwork with other partners.

We were dependent on other teams' work – so having a good relationship with them was also an important point in our development process.

Communication was the key point: the more we communicated the more we improved,. And thanks to this, our goal was to be one whole team. Here are some actions we followed in order to enhance this communication:

• Have a private place just for us. We created a separate channel to talk about the progress and solve any questions or doubts as soon as possible without extra meetings.
• Quick meetings. A meeting once a week worked great to check the progress on the main issues. But we did not always wait for this one meeting, and had a quick call whenever an issue needed to be discussed.
• Stay updated on the overall progress. We had a teammate from our team attending their daily standups and one of them at ours who updated the rest of the team if needed.

Here is some actual footage of us and the Integrations Team:

Make the client feel like part of the team.

At the beginning of the first MVP, there were too many clues and too little communication to clarify them so we were blocked sometimes or had to set up time-wasting meetings for these issues.

The core of the problem, like most problems in life, was a lack of communication. So we solved it by increasing our communication, asking questions directly to the client, inviting them to retrospectives, daily standups, and other meetings even when they were not required.

This helped keep the client updated as much as possible. In the end, the more we communicated the more we made them feel part of the team, and the better we worked together.

Final thoughts

I want to first thank my teammates. It has been a pleasure to work with them, starting each day eager to have fun together developing the project.

On the same level, thank you to the teammates from other teams who always gave a helping hand when requested.

I'm also thankful for the opportunity to participate in the full end-to-end implementation of the project from which I learned so much. I solved issues on Front, Back, and DevOps such as setting up environments, pipelines, messaging between services, persisting and retrieving data, serving it to the frontend, and implementing the interfaces to display it.

Finally, I am thankful for having the chance to work and get better at technologies that I was using on side-projects like GraphQL or TypeScript.

I hope you enjoyed this article. You can read it too on my site along with others! If you've got any questions, suggestions, or feedback in general, don't hesitate to reach out on any of the social networks from my site.

Whether you’re leading a team of people or leading yourself, it’s important to take account of all the important things that need doing in your organization. And to realize that this does not mean that everything can be equally important.

Logically, everything can’t be. Tasks are typically interdependent, and there’s always one task on which another depends. Tasks can be time-sensitive. Certain tasks might block a logical path towards a goal.

It’s the duty of a leader to make hard calls and decide which tasks are most important out of everything that needs doing. This necessitates comparing one to another, which is much easier to do with a centralized to-do list.

Here’s how this one simple change to your perspective on to-do lists can help to build happier and more productive teams.

Keep a central prioritized to-do list

Avoid working in silos. A single centralized list can make it easier for you and your team members to see what’s being worked on. With all tasks out in the open, it’s easier for people to spot opportunities for helping each other out and where they can contribute.

Encouraging a culture of openness can help people feel more comfortable asking questions, asking for help, and proposing ideas and improvements. Tracking work in the open also means that no one is left wondering what status a task is currently in.

For team leaders, a single list makes it easier to compare and prioritize tasks. This benefits team members by providing a completely unambiguous and transparent accounting of what needs doing next. Whichever task is most important, for the whole organization, is on top.

Priorities with autonomy

A single priority doesn’t necessarily pigeonhole someone into doing a task they don’t feel cut out for. Each member of your team has different strengths, skill sets, and diverse ways of thinking. You can take full advantage of this by encouraging autonomy in task selection.

Have people choose whichever task is nearest to the top that they’d like to tackle. They might pick the highest priority task that’s in their wheelhouse, or experiment with a higher one that’s in a domain they’d like to improve their skills at.

Embrace opportunities for cross-training. If tasks high up on the list fall in a category that only one or a few people on your team are experts in, have your experts partner up with another team member who’s taking on the task.

By pooling your resources to cross-train across domains, you multiply the capabilities of each team member and your team as a result.

When a task is especially time-sensitive, have several team members swarm on it and distribute the work according to their interests or strengths.

Make yourself redundant

Working off a single prioritized to-do list works best when your team members can take on tasks as independently as possible. This is especially important in remote teams where people work asynchronously.

If you’re a leader and find that your team members frequently ask you what they should do next, you could be making your team dependent on you. Ask yourself if you’re unnecessarily gatekeeping information that would let your team be more autonomous.

A team that overly depends on their leader is not an efficient one. Individual people, such as yourself, don’t scale. Don’t become a bottleneck to your team’s productivity.

A successful leader should be able to take several days off on short notice without productivity grinding to a halt.

To support your team’s ability to work without you, make your team, product, and company goals painfully available.

Put them where people hang out – your team’s message board, chat channel, or document repository, for example. No one should be at a loss when asked what the team wants to achieve next, and why.

Make any applicable resources, style guides, product documents, or links to external documentation painfully available as well.

If your team makes a decision about how something should be done, write it down. Don’t rely on yours or anyone else’s meat brain to remember an important decision, nor make yourself the only resource for recalling it.

Make yourself redundant when it comes to day-to-day work. Doing so empowers your team members to do work without you, think through solutions on their own, and propose paths of action that you probably wouldn’t have thought of yourself.

Build happier and more productive teams

From first-hand experience as both a team member and leader, I’ve seen how encouraging a culture of openness, cross-training, and autonomy makes for happier team members and more productive teams.

A single prioritized to-do list, coupled with available documentation and resources, opens the gates to let your technical team be maximally productive.

By removing bottlenecks, you allow people to make more decisions on their own and take ownership of their work. That’s a technical team I’d be proud to lead.

If you enjoyed this post, I'd love to know. Join the thousands of people who learn along with me on victoria.dev! Visit or subscribe via RSS for more about building happy and productive technical teams.

In my first software engineering role at an eCommerce brand, I often secretly worked on tasks outside of my core responsibilities. And many times I felt isolated from my teammates.

Therefore, when I was invited to participate in a project-based course to better my communication skills, I jumped at the opportunity.

For the program, I was assigned to a team with two other engineers and a team lead to build a full stack application using React, Python, and Flask. Now that the course is over, I thought I'd share the lessons I learned about how to be a better team player.

Lesson 1: Do not underestimate a project’s potential difficulty level

Since the course was meant for entry-level engineers, I figured I would have a leg up as I already had some professional Node.js experience. Granted, our tech stack would be using a Python Flask backend, but I figured Python and Flask would not be too hard to pick up.

On the first day of our project, we were shown what we would be building. Wow, I suddenly felt very unprepared. Our project was significantly more challenging than I had expected.

My other two teammates seemed to pick up the material easily. At the end of our first week I was our team’s least contributing member.

I knew React quite well, so our front end was not too difficult for me. But our backend was using PostgresSQL and Python, neither of which I knew well. It quickly became clear that the tasks expected of us would be particularly challenging for someone with little Python experience.

Lesson 2: Request feedback on work in progress

Initially, I often found myself wasting time doing unnecessary work. For instance, one time I was creating an editable user profile form, not realizing that my teammate was in the middle of building a reusable Material UI dialog component that I could have used.

Another time I spent time reading a tutorial on how to get the identity of an authenticated user, not realizing that my teammate had already figured it out.

Realizing how much time I was spending doing unnecessary work, I started posting in our Slack message board what I was working on and requesting feedback. My teammates were quick to respond. By having my colleagues give input on my unfinished designs, I was able to avoid duplicating work.

Lesson 3: When pressed for time, prioritize what to avoid learning

Given that I struggled to keep up with the workload, I needed to better prioritize my time. Whenever someone created a new feature, they would create a Git Pull Request (PR) to ask for the code to be reviewed. At first, I reviewed every PR and gave each of them my full attention. However, this soon proved impractical.

I remember spending lots of time reviewing the PR to add cookies and tokens for authentication. To do a proper review, I first read lots of background info on security issues such as cookies, local storage, and cross site scripting attacks. When I finished all that reading I read through the PR, only to find all the code made sense and there was nothing for me to comment on.

In hindsight, given how far behind I was with my own tasks, I should have ignored much of the cookie documentation and instead done just a rapid PR review to save time.

Gaining an in-depth knowledge of the inner workings of our cookie authentication was of little use to my overall productivity. In contrast, other PRs such as the one which set up React Context to pass state through our app directly affected nearly every feature that I worked on.

Prioritizing gaining a deep understanding of that PR would have been a far more valuable use of my time.

Lesson 4: Build new features by going from chunk to chunk

To get more organized, I had to learn how to skim through technical documentation. I called a senior engineering friend of mine, Sean Ellison-Chen, and asked his process for tackling a new feature that requires a technology that is brand new to him.

He explained that he first tries to understand at most 70% of what is going on, and then immediately starts building the feature in chunks. Each chunk gets committed to git.

For example, let’s say he needs to set up web sockets, he might set up a basic skeleton structure for web sockets, commit it to git, then work on the next chunk of setting up the correct socket events and so on.

By working in chunks, he ensures a smooth progression from tackling the bare minimums to eventually having a fully functioning feature.

Lesson 5: Request feedback from your team lead

Midway through the program, I received feedback from our team lead, Shums Kassam. I was told to ask for help more, to skim through documentation, and to leverage my teammates.

I took the advice to heart and upped the amount of times I posted in our message board. I started having video calls with teammates to review features I was building. I skimmed faster through the technical documentation and avoided the less critical areas. By implementing these changes, my rate of contributions sped up.

Lesson 6: Avoid doing a perfect job on tasks whose requirements might change

By sheer luck, I learned the importance of procrastinating on tasks whose requirements might change.

One of my first tasks was building a front-end form that lets users change their profile info. When I submitted my code for review, I was told the form’s appearance needed to be fixed as some of the input lengths did not match.

Normally, I would have spent the 45 minutes to fix it right then and there. But I was far behind in my contributions, so instead I just commented a “todo” about matching the input lengths and merged my code.

A week later, a teammate pointed out it would be a better user experience to combine the separate ‘street’, ‘city’, ‘state’, and ‘country’ inputs into a single ‘address’ input. When he simplified the inputs, my commented out “todo” was no longer applicable.

By procrastinating with working on the form, I had saved myself from doing unnecessary work.

Lesson 7: Be comfortable submitting non-refactored code

Near the end of our project, our team was rushing to finish all our features prior to a fixed date when we would present our project to an audience. We planned to have all features submitted well in advance to give us enough time to practice and rehearse.

But I ended up submitting my final feature with barely an hour to our demo and we had to rush to add it in. Though our presentation went well, I was troubled that I submitted the feature so late as it severely reduced our team’s ability to rehearse our demo in advance.

In hindsight I realize that instead of submitting optimized and clean code, I could have saved at least two hours of time by simply adding comments about refactoring later.

Over the past few months, I learned many lessons about how to be a better team player. Most importantly, I learned that teamwork is a skill that can be improved just like any other.

The program I participated in was run by Hatchways, a company that helps software engineers get their first jobs. At the time of this writing they service engineers and companies in North America. If you're an employer looking to hire interns or entry-level engineers see Hatchways - Employers.

Teams should set and uphold a set of values. These come in different shapes and forms. Whether it’s being honest, transparent, responsible, or blameless. The list just goes on.

Values are only important if they’re connected to behaviors, that is how you typically act regardless of the situation. Nobody behaves erratically over an extended period of time. After enough self-reflection patterns emerge, and those patterns can be associated with values. I’d like to focus on just two of them in this article.

The Enablers

Throughout my software engineering career I kept hearing the word enablement thrown out a lot. Now, first of all, enabling someone to do something can have both positive and negative connotations. I think it’s only in this industry that it’s acceptable to say you’re going to enable someone. In any other context you’d get some weird looks just for saying that.

So what’s special about an enablement team? Typically that means developing and maintaining components that other teams can benefit from.

If you ship software to customers you’re probably dependent on a continuous integration system. If it goes down, then you’re pretty much dead in the water. So someone, or a team of people, have to maintain it and keep it running close to 24/7.

Can you imagine your company right now shipping without your CI system? If not, then the team that owns it is enabling you to do your job.

The Gatekeepers

Gatekeeping is a word you don’t really hear much about. A gatekeeper is someone whose job is to not let anyone in to whatever they’re protecting.

The CI team is on the hook for its availability, they upgrade it from time to time, implement new features, fix bugs, apply security patches, etc. Given that everyone in the company depends on their work, it’s only natural to expect that they will always have a lot of planned work ahead of them. It’s common in a lot of companies that developers from other teams may be interested in helping them even though it’s not exactly their job to do so.

Should you be an enabler or gatekeeper?

Imagine you’re passionate about CI systems and you notice a problem with your company’s setup. It’s something you know how to fix, so you decide to just go ahead and do it.

After you’ve prepared your patch for submission there are really two different scenarios that could play out, and they have to do with values. Let’s see how the next steps would play out given two totally different teams, A and B, who uphold different values.

You talk to team A and they agree to review your patch. They suggest some improvements based on their experience, and work with you to deliver it. You gain more insights into what it means to actually be on the team.

You missed an edge-case and they point that out to you. You go back and fix it and re-submit, and your patch is finally accepted. They also let you know what’s coming down the road in the next months in case you find other issues.

You send your patch to team B. You don’t hear anything back for a couple of days, and decide to reach out in person. They tell you they’re swamped with work and don’t have time to look at your proposal.

You keep trying to convince them that it’s a small fix which greatly improves developer experience, but they don’t want to hear about it and finally tell you flat out that it’s not your job to think about CI. You give up and go back to work. Six months later they fix the issue but you only find out about it by accident.

Team B is what I’d call a gatekeeper team, even though their official mission is to enable, just like team A. They don’t let people in if they don’t have to. This team rarely benefits from the expertise of outsiders. It’s basically like comparing proprietary to open source.

But while I’m sure you’d rather interact with the former team, it may be useful to consider their perspective first before passing judgement.

It’s clear that team A values working together. If you bring an improvement to the table, they’ll take the time to review it, let you know if they were already planning on doing the same thing, or point out flaws in your solution.

Team B assumes that since you’re not on the team, you really have no business thinking about their line of work and you shouldn’t even try. But is team B’s behavior objectively bad? Like in all things software, it depends.

What if team B is maintaining a critical banking software component? If you were in their shoes, would you be so eager to let outside contributors in? What if your improvement contains a bug? If that happens it’s not your responsibility, you’re not on the team. They’re the ones who have to fix it.

Or perhaps their software is so complex there’s no way anyone on the outside would be capable of contributing without a lengthy on-boarding process.

You should also seriously consider that team A has to allocate time to work with you, so they’re making a call that you’re worth investing in. If it turns out your potential improvement would be a liability down the road, then they’re not getting that time back. It’s gone.

Team B in contrast is more draconian with their time. They consider themselves (perhaps rightfully so) experts in their field, and their assumption is, unless you’re on the team, you do not have enough context to suggest any improvements. You should only report problems to them and they’ll eventually get around to fixing them.

These are certainly extreme positions and I made them out to be so it’s easier to conceptualize. In reality teams are both enablers and gatekeepers, depending on the situation. But values always prevail, and it’s important to understand that when you need to work with other teams.

Guides to help you work remotely seem to have swept through the Internet these days.

Do this, avoid that, stay productive, and all those run-of-the-mill tips we’ve already tried out.

So instead of talking about how your remote team needs to schedule out their day effectively or clean their desk, here I am focusing on the hands-on tips you can apply to manage your software development team while working remotely.

First, we need to understand the exact meaning of “remote teams”.

This will allow you to clearly see that having even one individual who’s working separately means you should improve the way in which you manage your team and the process they use for remote team collaboration and task execution.

What are remote teams really?

Today, millions of companies are faced with remote work situations in one form or another. Whether they’re fully-distributed organizations, have a couple of employees working from another part of the world, or just regularly work with external collaborators.

The first thing that comes to your mind when you think of remote teams is something like: different people working from all parts of the world and distinct time zones on a single project and having the same general goals.

In reality, there are many remote teams that have employees in a single country or even in one city. It’s just that everyone works from their own home, without having to go to the office. ? This saves on costs while managing remote teams.

Source

But many companies (software development included) have offices in multiple countries. When your US team members talk to their colleagues from the UK, they’re essentially collaborating remotely. So remote team communication is a must in these cases even if everyone is in the office.

This being said, whether work is done from an office or not is not necessarily a defining factor for remote teams. The problems you could experience lie solely within the communication and work processes.

Best practices for managing remote software development teams across multiple time zones

Since you’re probably used to all the “do this to be productive” rants, I’ll try to tell you what you might not know.

Hire the right people for your remote teams

People are the heart of any team.

So if you hire the right professionals [and humans] for your team, you’re halfway to success.

On the hiring and interviewing process, here are some of the best tips from Shannon Hogue, Global Head of Solutions Engineering, @Karat:

“I always tell hiring managers to start at the review and work back to determine which core competencies should be listed in a job description. Then, to keep things standard across a global network of Interview Engineers, we put those competencies into structured scoring rubrics for each interview.

Here are 3 quick steps for building a structured rubric that can help keep everyone on the same page, be it for hiring or managing:

Identify what competencies are both relevant and important to assess.

For each competency, list observable behavior and results as checkboxes (select all) and/or radio buttons (choose one).

Write down an “algorithm” to help interviewers summarize a completed rubric into a single conclusion.

For example, if Technical Communication is a relevant competency you might list it on the rubric with a specific scale.”

Here’s what Shannon’s example could look like:

Beyond any hiring tip, effective remote work also imposes a question on whether your office workers will adapt to the new lifestyle.

If you’re switching from an office team to a distributed one or even if you want to hire someone who hasn’t worked remotely before, you need to guarantee they’ll fit in the team and work efficiently in your remote team even before day #1.

For software developers the demand is so high that you’ll often bump into this problem:

How do I make sure that who I’m hiring is the perfect fit within our team when they haven’t worked remotely at all? ?

Perhaps tech professionals are some of the easiest to assess beforehand. Check out any of their side projects, if they own a business or do freelancing, and even look at their online presence.

A developer who’s only been putting work for their official job and has no GitHub repositories and projects to boast is clearly not going to be someone you’ll trust right away.

Trust and accountability are the 2 main attributes to consider beyond any hard skills.

These two character traits (which we often ignore because we’re too focused on business results) can predict whether that person will fit within your team culture. And, even more importantly, if they’re willing to stay with your company for many years to come and dedicate themselves to your project.

From then on, managing remote teams is also a matter of how you handle their training.

Onboarding and training

The trial period all HR experts recommend exists for a good reason. It allows you to literally SEE how they work, collaborate, and get along with the rest of the team.

Many managers make the mistake of hiring a developer, letting them start the trial weeks, but not monitoring what they’re actually doing.

Don’t assume that someone who seems skilled and experienced will deliver the same commitment and quality of work to you too. May I say this is the best and only time to be a micromanager and literally oversee all of their actions.

But do offer your help within the first days by making sure they have all resources needed and making the appropriate introductions to your team.

Get them involved in the code writing process for your project as soon as possible so you can get a better feel of how they conduct their work. I’ll also advise you to try a pair programming session during the hiring process too. More on this procedure later in this guide.

Prepare the right work methods

This is largely the manager’s decision. Team feedback is only valid when everyone knows the relevant best practices and benefits of each work method. This doesn’t mean you can't get their input on the methods they’d prefer to use. However, letting them take care of the decision process will only give rise to conflicts and postpone the choice for the time being since there simply will be too many opinions for you to sort out.

“While you do not want to micromanage a remote team, you certainly want to set up clear minimum administrative processes. For a previous remote team I had to manage, this included setting-up very precisely the infamous JIRA workflow.

While it is good to leave a remote team some freedom, work also needs to be clearly organized, so there should be a few processes that have very precise descriptions. In development, the most important of such processes are issues management, and also the build process. This should be described in detail, and followed strictly.

To make sure key processes are respected, there should be set points when work needs to stop until the process is followed. As an example, I gave strict orders to my business team not to look at any incident that is not documented.” - Nicolas de Mauroy, CEO @Open Lowcode

But how close should supervision really be?

Surprisingly – not that in depth.

Keep your devs under your radar only enough to guarantee that all processes run smoothly and you’re able to maintain a trust both ways. Yes, 50% of data breaches across all industries are caused by insiders, but that doesn’t mean you must force everyone to track their time or record their screens.

Developers should really only have to track their time in 2 instances:

1. They/you really want to improve your work processes.
2. They’re getting paid by the hour.

Your role as a manager goes beyond the person who is seemingly in charge of everything. You’re a liaison. That key link between one team member and another, helping your development team collaborate with operations, marketing, design, customer support, and sales while also ensuring all team members are happy and their needs are met.

I’m super disappointed to tell you that only 35% of managers are engaged with their work. How is this going to motivate someone else?

Employees who are supervised by highly-engaged managers are in turn going to be better and happier performers themselves. This will boost your employee retention rates and create that long-lasting company-worker bond most companies can never attain.

This takes me to the importance of knowing when and how to communicate. Both ways.

Craft your remote team collaboration plan

Collaboration goes hand-in-hand with your work method and how you manage tasks. It’s the little things like crafting clear task descriptions and expectations that add up to distinguish a positive collaboration experience from a chaotic one.

Tinjo Thomas, Design Technologist @Coredes Interactive also recommends the following two tweaks you can make:

“1. Always set a due date for each task even though your developers are experts and can make estimates themselves.

2. If you are giving instructions to only one or two people, don't send the message to the whole group. Reach out to every individual in private. People spend a lot of time reading unnecessary conversations on channels.”

On meetings

Meetings are honestly a very controversial topic. Managers love to call meetings. Devs, though, hate most of them but are afraid to voice their thoughts.

To keep meetings relevant, here are some actionable points to keep in mind:

“On a more macro-level, knowledge sharing can happen through a weekly team meeting with a Q&A via video whereby the members of the team can share what they learned from the codebase with each other as well as ask questions. In terms of knowledge sharing through team meetings - you can have several types of meetings.

The overall idea for these is to encourage collaboration in an effort to turn explicit knowledge into tacit knowledge. So you can have brainstorming sessions or meetings geared more towards lessons learned (this can be in the form of a demo or presentation). All done entirely remotely.” - Emil Hajric, CEO @Helpjuice

One huge mistake first-time remote team managers make is filling up entire days with meetings:

“First-time remote team managers need to be quite aware of the differences between collaborative work [like Scrum meetings and software architecture design] and individual focus work [like coding]. It is important to schedule time and ensure everyone can contribute to the collaborative session, but then leave your professionals alone to do what they were hired to do, write great software.” - Pedro Henriques, Co-Founder & CEO @BRIDGE IN

You’ll want to always remember to press that record button during meetings. We’re not necessarily fans of paper trails, but you’ll need them to avoid bothering your team with issues that have already been discussed:

“You should be recording and saving absolutely everything from remote team meetings and strategy sessions. While working remotely, we've noticed a huge uptick in productivity when managers and team members can refer directly to meetings instead of having to play phone tag or email back and forth for simple information. It's a huge boon to workflow across the board and should really become the new normal with the increase in remote team management.” - Alexander M. Kehoe, Co-Founder and Operations Director @Caveni

Keeping up-to-date with all changes is even more important when your team’s distributed. But remote teams have different approaches to how they make sure they don’t just communicate, but also apply and consider every opinion.

Here’s where the real-time vs asynchronous communication battle comes in. Everything’s already been said about this. So the conclusion is:

There’s a right time for each type of communication. A predisposition for certain types of tasks will also make your remote team more likely to go for one method of communication over the other.

Just like the video vs written communication issue.

The Voro team, for instance, has used their office and remote communication tests to conclude that written collaboration worked best for them:

“My #1 tip for managing a remote team is to default to written communication rather than video calls. This forces you to clarify your thinking and communicate succinctly. When we all worked in the same office, it was easy to walk over to someone’s desk to talk through a problem. It would waste a great deal of time to replicate that with a scheduled video call.

Since we are 100% remote, more of our communication has been written, and we try to memorialize most of that in internal documents, so we continue to move fast and share institutional knowledge seamlessly.” - Tomas Hoyos, CEO @Voro

Invest more time in one-on-ones

With one-on-ones, you’re focusing more on sharing the status of specific tasks and individual activities, while every single member on your team gets to make their own suggestions. One-on-ones are commonly held between one team leader and the other members at a time.

Having these twice a month is your best bet to make sure everything gets covered. Holding them weekly is too often as you won’t have time to focus on your other tasks because you’re too busy with meetings.

These one-on-one meetings are also a good opportunity for you to hold reviews and updates on the OKRs. To facilitate the feedback and ideation process, Charles Ahmadzadeh, CTO @Bunch uses checklists during these meetings:

“I like to use checklists with my team. I'll ask each team member to create a checklist each day of what needs to be done before ending the day and before submitting their work. We review these checklists in 1:1s to spot patterns.

I mostly use this to help others around me grow or keep myself accountable to the feedback I receive from the team.

The good thing about them is that they work no matter how senior you are (even astronauts live by checklists). They’re easy to share in 1:1, even if your team is remote, and very simple to use, as long as you’re committed to improving yourself.”

NOTE ON OBJECTIVES AND KEY RESULTS: Team leaders can establish these at a team and individual level by also taking into account suggestions from developers.

For instance, each department or team can have specific targets: to release a feature on time, avoid more than 2 major bugs after a release, keep the error rate low, etc. Individually, each member should take care of one release so that every single team member will know how to handle them.

Here’s an actionable idea: Use TrackJS [or other error tracking tool for your programming language]. Every member can choose a top error and fix it. This allows members to increase their accountability and learn new things to avoid freezing their skills.

Pair programming finally getting the attention it deserves

Now is also the best time to experiment with pair programming. This practice allows two developers to work simultaneously, often on the same tasks. While this is usually done from the same computer, you can switch it up a bit and make use of tools like TeamViewer or screen sharing.

Pair programming also helps distributed teams improve the quality of their code, tighten bonds between colleagues, transfer information and know-how from one dev to another, increase their own accountability, and speed up the entire development process.

Does this make you feel like you’ve been missing out on all its benefits? ? Just keep in mind some best practices if you want to get started with using the pair programming practice on a regular basis.

By using common sense, you probably won’t have both developers working on the same thing for 8 hours straight. Instead, distribute tasks evenly and allot a specific time slot for them to actually work together. Dealing with multiple time zones? Pair programmers within similar work schedules.

Communicate beyond work with your remote teams

We’re all humans. So we can’t work, work, work all the time. How about you implement some activities for people to destress twice a week as part of your remote team management process?

Playing board games online. Having a #watercooler channel on Slack. Finding some creative online team building activities. These are all ideas to help your remote teams unwind and get their mind off anything that’s stressing them out.

Pedro Henriques also shared his thoughts on the importance of implementing this type of downtime while working remotely:

“Remote teams need to deliberately schedule slack time and create informal virtual watercooler moments. In the office, the watercooler or coffee machine is often the place for spontaneous discussions about various topics ranging from a nasty software bug to vent about office politics or even troubles in personal life. These discussions are not superfluous. They’re absolutely critical for team cohesion. Therefore managers should actively promote them, but make sure not to attend.”

Choose the right tools: The basics will do, there are no magical solutions

I’ve seen so many “best tools for remote work” lists the Internet could really crash for good.

Nah, but really, stop looking for the best apps and miraculous software to somehow save your remote teams.

We already know everyone is using Slack and Zoom to collaborate and the ones who don’t use these are probably doing so because of small issues they had or costs they wanted to lower.

For instance, from all apps I’ve tested for this purpose Google Meet was the fastest and most accurate one but guess what? My clients are using Zoom already. No room to impose another tool.

The key point is not to waste weeks trying to find the right tools for your team. Others have already done this. There are thousands of options out there. All of them are copying features from each other so you end up with the same tool in dozens of versions.

So here’s your stack:

Jira - Slack - Zoom - GitHub - InVision - a bug tracking tool - every developer’s code editor

Test these [preferably the free versions first] and only look for alternatives if you have huge issues that are stilting your workflow. My two cents.

Also, some wise words from Tinjo Thomas:

“Don't try to save money on bug tracking or team management tools. You will know why it’s important when things don’t get done as you expected.”

Know a remote team manager who could use these tips? Share this remote team management article with your network to keep improving remote work processes.

The COVID-19 coronavirus pandemic has resulted in many people working from home. So you might be wondering - how do I remain productive at home?

Remote work has been on the rise for years in many companies. Some offer remote work as a benefit to employees for better work-life balance.

And today, millions of people around the world have recently started working from home (WFH) because of the COVID-19 coronavirus outbreak.

Some companies do not advocate for WFH as they believe people cannot work without supervision. Instead, they adopted a controlling and micro-management culture.

However, which is a more productive environment for employees? The home office or the office office? Well, it looks like we have the opportunity to find out.

The situation may extend for weeks or even longer. Nonetheless, it is a great opportunity for a lifestyle change. There will be no rushing to leave home and skipping breakfast so that you won't miss the train.

A joint report by Buffer and Angellist surveyed more than 3,500 remote tech workers. It found that the top benefits of WFH are a flexible schedule, the ability to work from anywhere, and not having a commute.

On the other end of the scale, the challenges of team collaboration and communication become apparent when team members are dispersed in isolation. They also feel constantly attached to work while distracted by things at home.

WFH is awesome. To some, it may seem like newfound freedom, but along with it comes responsibility as well. To help with the transition into this new way of working, here are some useful tips:

Daily Routine

Be disciplined. It is important to cultivate strict routines or working hours, but also be kind to yourself. Wake up at your usual time and go through your usual routine. For me, I use the time usually spent on commuting to read or stretch my legs.

Dress properly. Do not wear pajamas. The way you dress can influence your mood and attitude, so dress in proper work attire.

Set work hours. WFH allows for flexibility, but the start and end of your work day should be as routine as possible. Enforce a hard stop at the end of the day, and plan for personal errands after that. Setting a target end time will dictate expectations and increase productivity.

Create a good routine with short exercise breaks. I personally feel that moving and stretching my body energizes the brain. The truth is, endorphins are produced when exercising, which increases happiness and interest levels.

Communication

Have a daily standup meeting with your team. This can be done remotely (whether standing or sitting). Just maintain the essence of keeping it short, and keeping team members accountable to one another in their respective tasks.

Have more social interactions. WFH can be lonely, so I do plan virtual coffee breaks with co-workers (with a real fragrant cup of coffee). Keep talking to people so you do not feel isolated.

Over-communicate. WFH means I cannot walk by a colleague to say something. If the matter is urgent, I usually do redundancy in communication. For example, after an email is sent, I also send a text message to the recipient, or leave a ping on Slack.

Use emoji. Text messages usually look more formal and serious on their own. To keep messages positive, sometimes I like to lighten the mood by adding a smiley face. There's a world of difference between saying DONE and done :-).

Distractions

Keep the television turned off. It is a big distraction. The radio or music on YouTube might be better if you are the type who works well with some background music. Relaxing jazz creates an unwinding mood, whereas video game soundtracks keep the energy level high.

Stay off social media. We are all guilty of this one from time to time, and social media can be one giant time-waster if you're not careful.

Separate space to work from space to rest. You should not work in the bedroom (the bed is so comfy! And it gives you backaches), and also not in the kitchen (You have full access to all the snacks! And it upsets your diet).

Leave Home. If temptations are too distracting, go to a WiFi-enabled cafe like Starbucks. A new environment is also a great stimulant for creativity and attention.

Time Management

Keep a daily checklist. Whether you work in the office or from home, it is essential to set a schedule for the day and keep track of daily tasks.

Use online tools. There's a lot of free software to improve productivity:

• Video conference: Skype, Zoom, Google Meet, Cisco Webex
• Tasks and project management: Air Table, NovaTools, Trello
• Team communication: Whatsapp online, Slack, Workplace by Facebook
• Shared documents: Dropbox, Box, GoogleDrive

Schedule frequent short breaks. Although taking breaks might seem counterproductive, research has shown that taking short breaks can actually increase productivity and creativity levels. Go get some fresh air outdoors, listen to the birds, enjoy the breeze, take time to smell the flowers, connect with nature with a short walk or cycle.

Avoid work creep. WFH can be invasive to your personal life. Without scheduled work hours, work can creep into your home life and just like personal errands can creep into work hours. Do not mix household chores into work hours.

WorkSpace Logistics

Prepare a conducive workspace. Apart from having a high-speed internet connection and a reliable router, get a comfortable chair and reserve a quiet space to be able to do focused work.

I have converted the guest room into a home office with ergonomic chairs, extended monitor screens, a full suite of stationery, and a printer. Most importantly, it is well lit and ventilated.

Use a comfortable headset or earpiece for calls. It is a good habit to mute your microphone during conference calls (unless you’re speaking) to minimize the amount of audio feedback and random sounds that interrupt the conversation.

Other hacks include: lower the video resolution when the network traffic is heavy, and use a collaboration tool to share your screen but get audio through the phone.

For Parents

Keep children in your plans. Due to school closure, children may also be around at home. Plan and schedule some activities to occupy them while you work.

Have staggered lunchtime to spend with children; for instance, one partner can have a lunch break at 11 am-12 pm, and the other breaks at 12 pm-1 pm, so 2 hours are spent with children.

For all we know, working with children around us might become the new norm from this season on.

Get family support. I am fortunate to have my mum to watch over the little ones during the day, along with a domestic helper to do the chores so my wife and I can focus on work.

This can be a good thing.

WFH is great for work-life balance. It increases ownership and performance. It trains people to be focused and disciplined. I look forward to seeing the productive benefits of trust and empowerment.

Everyone’s situation is different in terms of home environment, personality and habits. My advice is to ignore any tips that clash with your personal beliefs. Tailor the most effective way of working for you and keep practicing until it becomes part of a lifestyle or culture.

“It takes 21 days to form a habit”

Once a new way of working has been established all over the world, it might be hard to go back to the old ways.

Immediately when you start your work for the day, you probably check email, Skype, or Slack, as you are interested in seeing if your work colleagues have something important to tell you.

Then, when you write a response, the destination for your words is another person, not just another computer.

Your main priority at work is to solve problems, which is done while collaborating on projects and hanging out with other people as part of a software development team.

You attend meetings during the day and get the implementation requirements from other people.

When you are finally ready to do one of the most enjoyable activities for a software developer, which is writing code, you are supposed to write a code which is primarily readable for humans. You do not write your software projects in binary codes, but instead in a programming language that is supposed to be easier for both you and teammates to understand.

Even if you are working at a small company, or are a freelancer, you still have to deal with the non-technical people in the project that you are working on.

We spend a lot of our waking hours with our work colleagues. It is even possible that we spend more time with them than with our close family members.

Becoming aware of this will help you realize the importance of having good relationships with others, especially your co-workers.

In this article, you can read some general tips that can help you improve your relationships at work, but that can be applied elsewhere as well.

They are simpler to follow than the frameworks used to develop your applications, but these tips have a huge potential for return over investment.

1. Be very kind

Photo by [Unsplash](https://unsplash.com/@mimithian?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Mimi Thian / <a href="https://unsplash.com/?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit)

You can be the smartest and the hardest-working person you know, but when you do not have good manners or you lack kindness, others in your workplace might hate collaborating with you. Not because you lack the skills and the ability to write clean and maintainable code, but because of your attitude.

No matter how frustrating a bug is, do not pout, whine, or yell at your colleagues. Those bad manners will not be able to fix your bug. It can even harm your personal and professional relationships and make it very difficult to get back on track later on.

When you are kind, you are more likely to make a good impression on others as a human being in general.

Simple acts of kindness, such as giving someone a ride to or from work, mentioning someone’s favor in front of others, cleaning up a colleague’s space that’s not your job to keep clean, etc., should be done repeatedly, despite knowing your colleagues for a long time.

Your kindness will trigger, at least, a basic human decency from your colleagues as well.

2. Always be genuinely interested in your colleagues

Try to understand if they need your help, and do not hesitate to kindly help them. When you see that they are stressed, anxious, or going through tough times, talk to them and show readiness to brainstorm solutions about the problems they are involved in.

Even if you cannot help them with their current task, try to encourage them with motivational phrases that can uplift them emotionally. Make them feel that they are important to the team and capable of overcoming the obstacles they’re facing and the down times they might be in.

Your words alone can magically improve the mood of your colleagues.

3. Smile often

Even printing a ‘Hello world’ statement takes more time and effort than smiling and sending smiley emoticons. It may seem trivial, but smiling can lighten up the tension.

A scientific study conducted in 2011 at the Face Research Laboratory at the University of Aberdeen in Scotland found that smiling makes you feel more attractive, relaxed, sincere, and confident.

Moreover, one Swedish study published in the Scandinavian Journal of Psychology found that humans have an automatic reaction that mimics the facial expressions of those they interact with.

In other words, when you smile often, chances are that others will smile back to you as well. This will not only make you feel better, but it also helps others that you interact with.

4. Say ‘thank you’ and ‘please’ a lot.

No matter how small a favor is, do not hesitate to say thank you.

People appreciate when you are polite and grateful, and are aware of their contribution and significance in your life.

This will not only make your colleagues feel better, but it will make you feel better as well, as you will know that other colleagues care about you and are willing to help you.

Gratitude can improve your physical health, mental strength, self-esteem, the quality of your sleep, and can even reduce your stress levels.

Another word that you should frequently use in your communication with your colleagues is please.

When you use the word please, you are reminding the other team member that he is not forced to do something, but it would be kind, generous, and helpful of him to assist with the task that you are working on.

These simple words, no matter how insignificant they may sound, can make a huge difference once you start using them.

5. Praise other people’s efforts and stay positive

Photo by Tyler Nix on Unsplash

Become aware of other people’s accomplishments and praise every improvement, large or small.

Praising someone isn’t complicated. Common phrases like “Great job,” “Well done,” or “You did great” can be sufficient.

It may have taken a lot of effort and strong willpower to get to the solution of a frustrating problem.

When you praise others on their accomplishments, you make them feel important and that they are involved in something that has grabbed your attention.

As software developers, we tend to forget about the privilege of the skills we possess.

There are times when a small bug or an urgent task can bother you or your colleague for a few moments, but you should not let that distract you from the big picture.

You should regularly remind yourself and your colleagues about the joyful moments that you and your team have been through, and not let an occasional difficulty or a stressful situation make you feel disappointed.

Start the habit of regularly recognizing the efforts of your teammates and giving credit to them whenever the opportunity arises.

6. Do not hesitate to apologize

Nobody is perfect, and no matter how hard you try, you will always make a mistake here and there.

No matter how small your mistake is, do not hesitate to apologize about it.

Even though it might threaten your ego to apologize sometimes, it is a crucial way to keep good relationships with your colleagues.

Although you may think it will damage your reputation, by causing you to appear less confident, apologizing has the opposite effect.

It will remind others that you are aware of your shortcomings and that you are humble enough to admit to them.

Short phrases like “I am sorry” or “I apologize” can strengthen your ties with your colleagues, even during unpleasant moments.

7. Do not criticize

Criticizing is often perceived as a personal threat towards an individual’s ego, though you may not have intended to do that.

As a result, it is likely that they may get emotional and feel offended.

A better way of pointing out your colleague’s mistake is by giving them a polite critique: Call attention to people’s mistakes without demeaning them or making it personal.

Put yourself in their shoes and observe the issue from their perspective. Politely inform the other person about their mistake.

Do not point out a mistake in front of everybody; instead, do it privately.

If you want to inform everybody else about a mistake that they should not be doing, do not point fingers toward people, but toward the problem.

Try to focus on possible ways of solving the problem rather than on blame.

Become the person who helps people, rather than someone who belittles them.

When you help someone, you are going to feel your own sense of contributing and your own significance as well. Moreover, you can learn for yourself, and can also open doors to receiving help in future from the same colleagues that you have helped in the past.

8. Avoid arguments

Photo by [Unsplash](https://unsplash.com/@jasonrosewell?utm_source=medium&utm_medium=referral" rel="photo-creator noopener">Jason Rosewell on <a href="https://unsplash.com/?utm_source=medium&utm_medium=referral" rel="photo-source noopener)

We tend to think of ourselves as rational human beings, but in reality, we are emotionally driven creatures that can easily get angry.

Those few moments of anger can lead to some unpleasant arguments, no matter whether you are right or wrong.

Although you may be right, and protecting your opinion sounds like a good idea, arguing furiously with others is something that can dramatically ruin your relationships.

As Dale Carnegie mentions in his book How to Win Friends and Influence People:

“I have come to the conclusion that there is only one way under high heaven to get the best of an argument — and that is to avoid it. Avoid it as you would avoid rattlesnakes and earthquakes.”

The best thing to do about arguments is to try your best to avoid them at all costs. It is not as easy as it sounds, but it can become easier with practice.

Reminding yourself that most of the time there is almost no benefit from arguing, especially with your work colleagues, can reinforce the desire to keep yourself away from arguments.

9. Ask questions instead of giving direct orders

This is something that is more relevant to team leaders or managers, but it can apply to anyone else as well.

People tend to be more inspired to work when they are challenged to do something, rather than ordered around.

When you command someone to do something, their ego may come out and make the individual think that he is being oppressed or that his autonomy is being threatened.

Rather than giving a direct order, ask whether a colleague would like to work on a particular task.

If there is no other available developer who can work on a particular task, and you are afraid that they may not like working on the front-end side, tell them you are worried that the team might look bad in front of the client if this feature is not present in the next meeting.

Questions like “Would you mind working overtime and finishing off this task, knowing that this is critical for our project?” are better than commands like “You cannot go home unless you get this task done.”

Mention to them that they are an important part of the team, and they can help the team prove to the client that they are reliable for future projects as well, with questions such as, “Could I possibly assign this task to you, knowing that you are already experienced with these types of work?”

10. Avoid dealing with ‘toxic’ people

Even though working as a software developer might be your dream job, there may nevertheless be toxic people at your workplace.

You thought you left those types of people behind at your high school, but it turns out that life is filled with so many of them.

These people are simply looking for opportunities to bring others down and may generally possess a negative perspective on everything in life.

You can try to change them with your well-intentioned influence, but often it is very difficult for a person to change (for a lot of reasons).

If you see that you are not having any positive influence, and associating with them is only causing you trouble, then you should avoid dealing with them.

You might be in a situation, however, where this person is your manager or a colleague in your office.

In these cases, your alternatives are very limited. You may consider changing your department, or start looking for a new job.

In cases when you do not have any other alternative but to deal with them, prepare yourself mentally ahead of time regarding their bad attitude, and tell yourself that you should not let them influence your mood and ruin your whole day.

Their attitude is not something that should surprise you.

Try to interact with them as little as possible.

Conclusion

There is a lot more to the life of a software developer than just writing code. Dealing with people is one of the key factors.

Although they do not get mentioned or emphasized that much, social skills are among those few seemingly unimportant skills that can actually accelerate growth in your career.

And they are much simpler to understand and put into practice than inverting a binary tree on a whiteboard.

While I agree that some of these things are easier said than done, it is important to practice applying them in our lives.

Before you leave, let me kindly remind you about one more thing: Do not expect to always be able to apply these things all of the time.

We are human beings and we have our own difficult times, too.

However, we must not let those few moments of frustration and anger ruin our whole professional and non-professional lives.

We all learn about web accessibility at different points in our career. That means a lot of time you are not on the same page as your teammates. I had the privilege a couple of months ago to speak at Pingboard about accessibility. Our goal was to get the whole team at the same knowledge starting point. If we all have a basic understanding of whom web accessibility affects and how it affects them, we can ship better experiences.

You probably find yourself in the same opportunity at your company to present on accessibility. So I would like to do two things to help: I am going to give you my presentation as a starting point and walk you through the points I like to touch on.

You probably find yourself in the same opportunity at your company to present on accessibility. …I am going to give you my presentation as a starting point and walk you through the points I like to touch on.

Remind the team that you are talking about real people.

When we read accessibility documentation, it is easy to forget the human element. It makes sense because you are reading technical docs meant to influence code. It is great to start with this shared definition:

A person with a disability: A person who has a physical or mental impairment that substantially limits one or more major life activity.

We use this to establish friendly dialog. People do not want to be called “disabled”. They want to be called their name. We also need to clarify how wide of a range disabilities can be. Try expanding past assumptions early on with these points:

• Some disabilities come at birth, some come later.
• Some disabilities are permanent, some are temporary.
• Some disabilities always affect, some come and go.
• Some disabilities are visible, some are invisible.

Go over some disability categories with emotional experiences and quick tips.

Now that we have established that we are talking about people, it is time to talk about their experiences. I like to mix this section with quick tips for common disability categories. Remind your audience that there are way more disabilities than you are covering. They are difficult to categorize, which is why the technical documentation focuses on the solutions.

Something you will notice about the presentation is that there is a lot of video and audio. I find it more effective to have those with disabilities speak more than me about the issue. The multimedia in the presentation makes it possible for those people to not even have to be there.

Visual

I love to share this video of Tommy Edison using a screenreader because he keeps things lighthearted, but also goes through the whole process of sending an email. After the video, you can point out that fellow Mac users can try their screenreader with CMD + F5 at anytime.

Quick tips:

• People with dyslexia prefer to override font settings.
• People with low vision need to be able to zoom correctly.
• People with color blindness need an overall color contrast ratio of 4.5:1. Text 19px or larger can have a ratio of 3:1.
• People with color blindness need labels and patterns for differentiations.

Auditory and Seizure

Auditory disabilities are easier to talk about with digital product teams. Remind your team that all audio should be paired with visual cues and captions. Encourage the team to do content audits to check all videos for closed captioning.

Strobing, flickering, and flashing can trigger seizures. Other triggers include animations longer than 250ms, parallax, and images moving under text.

Motor

There are two demos I like to show teammates when it comes to motor disabilities. The first is hidden inside a longer video. A fellow named Gordin Richins shows what it is like to use a mouth stick. It is an older video, but I try to point out that new technologies can be more expensive.

The second video is a wholesome video of an eye tracking product. These are great because they can provide mouse capabilities to those with motor disabilities. However, we should still make all experiences keyboard accessible to be safe.

Cognitive

Cognitive disabilities can be difficult to convey. For this last category, I stuck with quick tips to keep the presentation alternative between facts and emotion. Here are the quick tips I share:

• For memory, keep processes short and remind users of context as much as possible.
• For problem-solving, error messages should be as explanatory as possible.
• For attention, use visual cues to highlight the most important points or sections of content.
• For reading, linguistic, and verbal comprehension, provide supplemental media that helps processes.

Emphasize how common disabilities actually are.

Did you know that one out of five people in the US have at least a one disability? (source) It may not seem like that in the workplace, but we should consider why. This is the point of the presentation when people should understand invisible disabilities. Invisible disabilities can be hidden from the naked eye. Here is a great interview where Carly Medosch talks about working with an invisible disability:

NPR: People with 'Invisible Disabilities' Fight for Understanding

This story is a great transition to a big question: What can we as enterprise software teams do to help those with disabilities?

Well, 79% of people of a working age in the US have employment. Only 41% of people of a working age in the US that have disabilities have employment. (source) If more jobs were accessible, that gap would close. This means that we as enterprise software teams can make it our mission to close the gap!

End with the legal risk for those that need extrinsic motivation.

It may not feel great, but some people may still need more reasoning about why the team should work towards accessible experiences. This is why I like to close the presentation on the legal implications of accessibility.

ADA Title 3 lawsuits in federal court: 2722 in 2013, 4436 in 2014, 4789 in 2015, 6601 in 2016, 7663 in 2017, 10163 in 2018. https://www.adatitleiii.com/2019/01/number-of-ada-title-iii-lawsuits-filed-in-2018-tops-10000/

In 1990, the Americans with Disabilities Act was signed. This provides those with disabilities the same protection that’s given in the Civil Rights Act of 1964. Section 508 says digital experiences in government departments and agencies have accessibility requirements.

Lawsuits continue to grow saying that the ADA also covers digital experiences from any company. Over 10,000 lawsuits were filed in 2018 alone. In fact, one of those cases is headed towards supreme court.

Be a part of the good fight.

Are you considering presenting to your team on web accessibility? You really should. You don’t have to be an expert and it’s okay if not everyone listens to you. Every effort to make the web a more friendly place is worth it.

I hope these resources helped you shape a future presentation. Please steal everything from me (but keep the citations).

If you appreciate this, please consider voting for my SXSW talk idea. I want to teach product managers, designers, and everyone else about progressive web apps. The cool thing about PWAs, is that a lot of accessibility criteria is baked in! If you wanna learn more, check out the video below.

Please take minute to vote for my talk and share it with others.

Got any other good resources for accessibility presentations? Please share them in the comments or tweet me them at @seejamescode. I will retweet the best ones!

When you are coding, interruptions really suck.

You are in the zone, flying high, killing it. And BAM… meeting, standup, insert interruption… Great!

In that context, code reviews can be perceived as another hurdle to productivity.

And frankly I can relate to that.

Code reviews are hard.

Not only do you need to stop what you are currently doing, you also need to immerse yourself into somebody else’s code. It takes a lot of energy just to switch your focus.

Code reviews are time consuming.

According to Slack Overflow’s 2019 survey, 56.4% of developers spend 4 hours or more per week performing code reviews. And it can represent up to 20% of a developer’s week!

Code reviews are frustrating.

As a submitter, it can be frustrating to get your pull request rejected, to wait hours if not days for a review. As a reviewer, code reviews can feel like an obstacle to a good productive day.

Yes, code reviews can sometimes be hard, time consuming and frustrating.

But they’re also a good way to share knowledge, prevent bugs, and reinforce your company’s culture among other things.

What follows is a manifesto for submitters and reviewers to bring back peace of mind into code reviews. ?

A Submitter’s Manifesto

As a submitter, here’s what you can do to increase your chances of getting your pull requests approved in a timely manner.

Submit when you’re done.

It sounds obvious, I know. But the thing is — most of the time if the machine doesn’t work, it’s not because it’s broken… it’s because it’s not plugged in!

Very small details can make a big difference on how your work is perceived. And you don’t want your colleagues to feel they are investing time and effort into reviewing work in progress code.

Me: “It was just a missing !”

You: “Yeah I know, but the whole thing didn’t work and it took me 20 minutes to spot it.”

So here’s what you can do:

• Self-test your code. Include WIP in title or label if you’re not done yet.
• Self-review your code. Use the diff report of your code editor or versioning tool to catch mistakes.
• Make sure the tests of your CI are green before assigning a reviewer, this will save them time.

_Don’t be this guy, obviously ? (G[iphy)](https://giphy.com/" rel="noopener" target="blank" title=")

Make smaller pull requests

I get it, it’s a big, important and complex feature and you might be tempted to submit a long pull request. Yet, most of the time, you are better off submitting smaller pull requests.

Code reviews take energy. Big code reviews even more. Don’t impose on your team a developer vs food challenge every time they review your code.

Be nice, cut it in smaller chunks. You are also doing yourself a favor:

• You’ll get more qualitative feedback. The longer a pull requests the fewer qualitative feedback per line of code you’ll receive. Keep your pull request small (not too small either) and you’ll increase your chances of getting great feedback on it.
• You’ll get them approved faster. It’s a win-win, by breaking down your work into smaller pull requests, you increase your chances of getting them approved faster.

LGTM ?

For the nerds out there, here’s a study conducted on a Cisco programming team. It shows that after 400 LoC the ability to find defects diminishes pretty dramatically. ?

The next principle helps with keeping pull requests size under control.

Narrow the scope

The scope of your pull request should be simple, unique and well-defined. That might be a feature, a user-story or a bug fix.

Making the world a better place, one LoC at a time ?

One way to think about it is that reviewers have a limited number of “attention credits” (like everybody). Every time they focus on something, they use 1 credit. What happens when they have 0 left?

LGTM ?

Do what you can to reduce the noise around your work. Be mindful of the reviewer’s attention span.

For instance, avoid void changes (like skipping lines). They don’t add any value and complicate the code review.

Similarly, if your pull request changes the behavior, don’t include changes to formatting. Conversely, if your pull request changes formatting, don’t include changes that affect the behavior. They might be overlooked by the reviewer.

Give context

Think about your pull request as documentation for new comers. Guide the reader with context.

Start with a self-explanatory title.

Good title taken from the xg2xg repo ?

Then, write a clear description to explain what you are doing and why are you doing it. What is the purpose of this pull request? Why is this change necessary? How did you approach this problem?

Good example of explaining why the change is necessary taken from react repo

The description is also is great place to point out unresolved issues and open questions. Reviewers might have suggestions to unblock you.

Are you working on a visible part of the product? Screenshots can help get your point across faster.

• Show before/after differences.
• Use colored arrows.
• Add screen recordings if you feel like it :)

From react repository

Finally, write information signs along the way to guide the reviewer through your reasoning.

Keep a clean commit history to make it easier for the reviewer to follow your step. Use comments to point out alternatives you explored.

Good comment example from Lodash

Welcome feedback ?

Rejection hurts.

Truth be told, code rejection hurts even more.

I’m seeing this a lot!

It’s alright. Don’t take it personally.

Comments and suggestions are an opportunity to learn and become a better software engineer ?

A Reviewer’s Manifesto

Congrats on making it this far! Now let’s look at a few principles that might help you become a better reviewer ?

Adopt the right mindset

There is no scenario where a team can benefit from a reviewer being mean or patronising. Be kind. Period.

_What are you trying to say my friend? ([Giphy](https://giphy.com/" rel="noopener" target="blank" title="))

Want to make code reviews more exciting?

Look for something you can learn from this review. A new library, a new method, a new concept, a simpler way to do things. What piece of knowledge will you extract from it?

If you are the more experienced developer, is there something you can share? How can you use this review to transfer knowledge to the submitter? How can you help them become a better software engineer?

Thanks for the tip mate! ?

How to actually do a code review

What to review

What am I even supposed to look for? Without clear guidance on what and how to review, it’s easy to get lost. Here is what you can do.

First off, check the purpose. Is this code accomplishing what it is meant to do? Are there parts of the new code that are not clear to you? Ask clarifying questions. The code is easily testable? Test it. There’s no need to go beyond if this square is not checked.

Ok now that the code works, time to focus on the implementation.

Think about how you would have approached this problem. Would you have done it differently? Is there potential for refactoring or abstraction? Is this re-inventing the wheel? Is this using standard code patterns?

What to not review

Because a piece of code has room for improvement, it doesn’t always mean it needs to be improved.

At the end of the day, code reviews are a tradeoff between quality and velocity and depending on the scope and stage of the project it might make sense to let a few things behind.

Similarly, you shouldn’t be doing things that can be automated. Let your favorite linter hunt for the missing semicolons and extra indentation. No need for an endless debate on tabs vs spaces.

Finally, don’t increase the scope of the pull request. If you think of new things that need to be done, create a new pull request /task for that matter.

Review in a timely manner

There are at least 3 good reasons to review pull requests in hours rather than days.

• The submitter can move to the next task quicker
• It reduces context switching cost
• It reduces the risk of merge conflicts between branches.

Opened 6 years ago. Be right back ?

Disclaimer: I just released GitRise, a tool that helps teams using GitHub & Slack review pull requests faster. I do think it can help with this one :)

How to give feedback in a code review?

When giving a feedback, the form matters as much as the substance.

Did you know that in written communication, neutral content looks more negative than it actually is? Beware of this bias and include emojis when needed to get the tone right in your comments.

Also, most of the time, even if you are pretty sure that there is a better way to do something, you are better off asking a question rather than requesting a change. Plus, questions sound less aggressive.

Example from ember.js repo

Finally, reward when things are done right. Code reviews are also a great place to give kudos to colleagues for doing a good job. Be creative and fun :)

? Congrats on reaching the end of this blog post!

? Thanks a lot for reading and let me know if you have any comments!

? I just released GitRise, a tool that creates pull requests reminders for teams using Slack & GitHub. Give it a try if you want. Looking forward to your feedback.