Forem: CodeStream

How we extended GitLens’ Pull Request functionality in Visual Studio Code

Brian Canzanella — Fri, 15 Jan 2021 15:23:53 +0000

GitLens, the incredible git-toolbelt extension for Visual Studio Code, recently added the ability for other VS Code extensions to tie into its user interface.

Specifically, it added additional touchpoints around the ability to create and view pull requests. As a developer of an open source VS Code extension (CodeStream), this seemed like a great way to give out users additional choices with regard to how they create and view their pull requests.

Here comes the technical parts!

At CodeStream, we use TypeScript, so you'll need a definition file for the GitLens api. I have this saved in @types/gitlens.d.ts

import { Disposable } from "vscode";

export { Disposable } from "vscode";

export interface CreatePullRequestActionContext {
    readonly type: "createPullRequest";
    readonly branch: {
        readonly name: string;
        readonly remote?: {
            readonly name: string;
            readonly provider?: string;
            readonly url?: string;
        };
        readonly repoPath: string;
    };
}

export interface OpenPullRequestActionContext {
    readonly type: "openPullRequest";
    readonly pullRequest: {
        readonly id: string;
        readonly provider: string;
        readonly repoPath: string;
        readonly url: string;
    };
}

export type ActionContext = CreatePullRequestActionContext | OpenPullRequestActionContext;
export type Action<T extends ActionContext> = T["type"];

export interface ActionRunner {
    readonly label: string;

    run(context: ActionContext): void | Promise<void>;
}

export interface GitLensApi {
    registerActionRunner<T extends ActionContext>(
        action: Action<T>,
        runner: ActionRunner
    ): Disposable;
}

Inside your extension's activatefunction is where you can create this integration. Below, I've added a simplified version of what we finally went with. The main idea is to find either the stable version of GitLens or the insiders (aka the nightly version) and listen for "openPullRequest" and "createPullRequest" attaching using the GitLens api registerActionProvider method.

const gitLens = extensions.getExtension<Promise<GitLensApi>>("eamodio.gitlens") ||
extensions.getExtension<Promise<GitLensApi>>("eamodio.gitlens-insiders");
if (gitlens && gitlens.isActive) {
 const api: GitLensApi = await gitlens.exports;
 api.registerActionRunner("openPullRequest", {
  label: "CodeStream",
  run: function(context: OpenPullRequestActionContext) {
   console.log(context, "it worked!")
  }
 });
 api.registerActionRunner("createPullRequest", {
  label: "CodeStream",
  run: function(context: CreatePullRequestActionContext) {
   console.log(context, "it worked")
  }
 }); 
}

Our implementation was a little more involved since we wanted to ensure that GitLens was actually active before attempting to register. There isn't a great way to truly know when another extension is active, so we used a polling mechanism. As noted in a comment in the code, there is an open issue with the VS Code team to address this.

Our complete solution can be found in the CodeStream repo on GitHub or alternatively on CodeStream itself.

Look out for this feature in the next version of CodeStream!

VS Code, GitHub, and CodeStream: Choosing the best of all worlds

Claudio Pinkus — Wed, 13 Jan 2021 17:37:13 +0000

There is consensus among the thousands of developers we have surveyed that context switching is detrimental to productivity and staying in the zone. One way to reduce this is to integrate the essential tools developers use every day into their IDE. According to the latest Stack Overflow survey, the tools developers use most are GitHub, Jira, and Slack. In this post we will focus on the GitHub integration in Visual Studio Code.

GitHub has been integrated into VS Code for some time now, with versions released prior to Microsoft’s acquisition. The GitHub Pull Requests and Issues extension, now under Microsoft’s ownership, has been downloaded about 1.2 million times and has received an average of 3 stars in the Visual Studio Code Marketplace. Many of the recent reviews are 1 star, as GitHub decided to discontinue its support for GitHub Enterprise. In addition, many reviews state that the extension is very buggy, or just does not work.

If you are interested in integrating GitHub in your IDE, CodeStream offers a better alternative. The CodeStream extension for VS Code supports GitHub Cloud and Enterprise, as well as GitHub issues. If you are not a VS Code user, the CodeStream extension for JetBrains is also available with the exact same functionality. The CodeStream extensions have been downloaded about 300,000 times and have an average rating of 4.4 stars. Many reviews praise the functionality and quality of the extension declaring that it works well and is a great tool for code reviews.

If you are one of those GitHub users who prefers an issue tracker from someone other than GitHub, CodeStream lets you integrate with any of 15 different trackers including Jira, Asana, Trello, Azure DevOps, Linear, and Clubhouse.

In addition to integrating with code hosts (CodeStream also supports GitLab and Bitbucket, but not yet for Pull/Merge Requests) and issue trackers, CodeStream includes a built-in code chat solution that enables frictionless code discussion and integrates with Slack and Microsoft Teams. CodeStream also allows you to request feedback on unreviewed commits without the need for a pull request with just two clicks.

The table below summarizes the comparison between the Microsoft GitHub extension and the CodeStream extension for Github.

Both the CodeStream and the Microsoft Github extensions are free to use for an unlimited number of users indefinitely. If your organization is very security conscious when it comes to code, CodeStream also offers an on-premises version available for a free trial, as shown here. The paid version also includes premium support and reporting features.

JetBrains Space vs. CodeStream

Claudio Pinkus — Thu, 07 Jan 2021 16:12:58 +0000

In December, JetBrains announced general availability of Space, an all-in-one solution that aims to replace an array of tools for the whole organization, from Slack to GitHub, Jira to CircleCI, and everything in between. It’s an ambitious project reminiscent of discontinued integrated environments that faded over time, such as Lotus Symphony – I know, I am dating myself – as single-purpose tools such as Word and Excel emerged as the preferred solution for knowledge workers.

The Microsoft Office Suite (a collection of single-purpose tools) never evolved into a single integrated environment and went on to dominate the office space. Google took a similar approach to the Google Suite. In software development, the most widely used tools today are VS Code (Microsoft), GitHub (Microsoft), Jira (Atlassian), and Slack (soon, Salesforce), as reported in the 2020 Stack Overflow survey. Still, many other companies have significant market share in their niche. JetBrains is well-entrenched as a provider of text editors or IDEs. GitLab offers a powerful code host along with DevOps tools. CircleCI is a market leader in Continuous Integration. And the list goes on. Even the mighty Microsoft has not been able to own every segment of the software development lifecycle, though it keeps trying.

According to a post in Techcrunch, the ultimate goal for Space is to provide a unified company-wide platform expanded to a wider range of creative teams, including designers, marketers, sales, accounting, and more. Seems like a tall order. The problem JetBrains is trying to address is that the array of tools “...leaves people switching tools and tabs, manually copying information, and generally losing time and creative flow” according to CEO Maxim Shafirov. At CodeStream we share his view that it’s a big problem development teams need to address, but our solution is quite different.

First, we are focused exclusively on developers, because they are drastically underserved when it comes to integrated solutions, and in particular, have unique needs when it comes to communication tools that are code aware. This point is fundamental when it comes to reducing context switching. Second, we aim to deliver a seamless solution by integrating the tools developers already use into the IDE of their choice, rather than adding yet another separate app into the mix. CodeStream supports 14 different IDEs, including all of JetBrains’ and Microsoft’s. It integrates with over a dozen issue trackers from Asana to Jira, to Azure DevOps, six code hosts including GitHub and GitLab, both cloud and on-prem, Slack, Microsoft Teams, and e-mail.

Here is a table that summarizes the main differences between JetBrains Space and CodeStream:

If you envision moving all of your collaboration to a single app that replaces your existing tools and workflows, then JetBrains Space looks like a good solution. If you would rather find a way to reduce context-switching, improve collaboration and boost productivity while still retaining the tools and workflows you are currently using, then CodeStream might be right for you.

Fixing a broken software development process through better technology

Claudio Pinkus — Wed, 04 Nov 2020 21:21:41 +0000

Introduction

The software development process keeps evolving to keep up with the demands of the enterprise. As software is (famously) eating the world, more and more organizations make more software, have more frequent changes, requirements and integrations, and must manage a global workforce of developers. Software is now discussed in boardrooms as a strategic asset that drives value creation. In addition, work-from-home is the norm, at least for now, and the trend might stick for the foreseeable future. All this is straining the traditional approach to managing software projects. The assumption that a small team, co-located in an office, can easily communicate, plan and execute is no longer valid. A new approach is needed.

A collaboration gap

The typical planning process for software development teams is structured around a sprint. It starts with (a) the allocation of tasks, followed by (b) the execution of those tasks, such as developing a feature, and it ends with a (c) code review triggered by a pull request. During phase (b), developers typically don’t collaborate much. By the time a code review begins, often after a week or two of coding, the amount of work required to rework a suboptimal solution often leads to compromises and the accumulation of technical debt.

The code review process, which typically involves the developer and one or more reviewers, is also meant to share knowledge about the codebase. While ephemeral knowledge is exchanged among the immediate participants, that knowledge is not captured in a digestible form and is not widely available to other developers in the organization. That leads to a knowledge gap that manifests itself clearly when key developers leave the organization.

While developers spend most of their time in the Integrated Development Environment or IDE, IDEs have until now not served as collaborative tools and do not include the essential communication, project management and knowledge sharing components that reduce collaborative friction. Therefore, developers must jump from their IDE, to Slack, to Jira, to GitHub.com, to email, many many times per hour, in order to collaborate. This context switching is highly inefficient, disruptive, and going forward, unnecessary.

Shifting Left in Developer Collaboration

In the last decade, the Shift Left Principle has taken over the software operations and quality assurance process under the newly coined term DevOps. As defined by AWS “DevOps is the combination of cultural philosophies, practices, and tools that increases an organization’s ability to deliver applications and services at high velocity: evolving and improving products at a faster pace than organizations using traditional software development and infrastructure management processes.”

Still, the “Dev” half of the DevOps equation remains less automated, less collaborative and less efficient than the “Ops” side. According to Devopedia “The principle of Shift Left is to take a task that's traditionally done at a later stage of the process and perform that task at earlier stages.” The answer we are looking for in addressing the deficiencies in developer collaboration might be a combination of shifting left from a cultural perspective while adopting practices and tools that integrate the essential tools into a collaborative environment.

The IDE becomes the Hub

While the software development process has always involved many participants, the IDE has generally been seen as a standalone, single player tool. In order to stay in the zone, developers shunned distractions, and the IDE was intentionally kept isolated from the communication and collaboration aspects of the software development workflow.

GitHub, Jira and Slack are the most widely used tools among developers, according to the 2020 Stack Overflow Survey. All three are part of the collaboration required to produce high quality software on time. But none of them were integrated with the IDE as a natural environment when code is written and all appears in context. GitHub is mostly used in a web browser, causing regular context switches between the IDE, the command line and back to the browser. Collaborating in Slack requires developers to copy and paste code, a tedious and infrequent task, and then to explain to the recipient the context that was just lost through the cut and paste operation. Over the last 20+ years we've seen incredible innovation in the browser, as web technologies make it easier to deliver robust and compelling user experiences. So perhaps it's no surprise that Jira, Github, and Slack are all web-based.

Starting with the Atom editor 6 years ago, and more recently popularized by VS Code, editors can now be extended with web technologies. This opens up the possibility of bringing these powerful capabilities directly into the IDE. Since context switching represents 70% of the steps involved in the unintegrated developer workflow, the same work can be accomplished with ⅓ the effort in an integrated environment where pull requests, issue tickets and messages are associated with the code itself.

From Transparency to Visibility

Many organizations are striving for transparency as a matter of cultural adaptation. When transparency is implemented, better alignment is possible. Communication becomes more streamlined and overlapping departmental and personal responsibilities are better clarified and defined. In order to become more transparent organizations must deploy technologies that increase visibility.

Examples abound: Many teams share calendars in order to coordinate schedules and meetings, many of us set our status on Slack or Microsoft Teams to show our availability, and in this year of Working From Home many have chosen to keep a Zoom call open among team members to be able to casually discuss ad hoc issues. Still, software developers keep working away in their IDEs after grabbing a ticket and emerge from their focused sprint with an almost finished product. If the individual IDEs were connected to each other in a team setting, increased visibility could be possible. Team members could see what the others are working on, team leaders could help out someone who is blocked, and software quality would improve on the first pass.

A New Workflow is Desirable

It is both possible and desirable to integrate the essential tools developers use every day in order to boost collaboration, timely communication and reduce errors and technical debt. The technology is available. The most important step now is to redefine what’s acceptable from a cultural perspective so that developers can feel free to share imperfect work early that is made dramatically better by the contributions of their peers, thus fostering shared knowledge.

We must step forward in the direction of a new modern workflow where integrations are the norm, code reviews happen sooner and more often, and knowledge is shared effortlessly through technology.

Human-Centric Code Reviews

Brandon Hopen — Tue, 26 May 2020 16:47:37 +0000

Code reviews can be a great opportunity for software development teams to learn, mentor, and collaborate with one another. However, they can quickly become cumbersome if colleagues are not thoughtful with one another in how they communicate feedback during the process. All too often teams focus on providing the best technical guidance to developers while ignoring the psychology on how to deliver feedback. Ideally, the code review process touches upon elements of the psychology of the team as well as the technical workflows. Microsoft, for example, has implemented a number of strategies for providing feedback that includes a mix of both of these considerations. A code review model that fails to utilize feedback mechanisms on how team members actually learn and absorb information can risk jeopardizing team chemistry in the middle of a sprint.

Here are some best practices we recommend to increase the effectiveness of providing feedback during code reviews:

1. Conduct code reviews more frequently: provide rewards for completing more tasks

According to a study at Cornell, “people who received immediate, frequent rewards for completing small tasks reported more interest and more enjoyment in their work, compared with people who received delayed rewards only given out at the end of a long project.”

Institute a regular practice of developers submitting smaller, bite-sized code reviews frequently rather than waiting at the end of a process for feedback. If managers regularly reward developers with feedback during each step of the way, even during a work in progress, then developers are more likely to stay motivated during the course of a project.

2. Provide feedback with the same expressions and terms a colleague used when they submitted their initial code review

Adopting the same language, pitch, and tone as a counterpart establishes trust between two parties. Mirroring the way another person communicates is likely to help with problem-solving. In a study, published in 2008 in the Journal of Experimental Social Psychology, 62 students were assigned to negotiate with other students. Those who mirrored others’ posture and speech reached a settlement 67% of the time, while those who didn’t reach a settlement 12.5% of the time.

If you are discussing a change and are communicating through messaging and comments, it’s important to be thoughtful about how your language comes off. Reviewers should strive to maintain a sense of psychological safety to discuss a problem. Both the reviewer and developer should try to use common terms both parties are familiar with.

Of course, these changes should be subtle and a reviewer should not blatantly mimic the expressions of the developer, as that has proven to backfire.

3. Be considerate in how you frame comments to a colleague

A doctor walks up to two recently diagnosed patients with the same critical illness but presents the information differently. The doctor says to one, you have a “95% chance of living”, while saying to another, “you have a 5% chance of mortality.”

How you document feedback and message important information to the developer matters. To improve the cohesion of a team, managers should be thoughtful in their feedback and not assume that there is one way to present a point of view to the developer. Reviewers should be cognizant of the language they are using and document how particular feedback impacted the quality of the review. Reviewers should then have a source of data to understand the best method of delivery.

4. The end of a reviewer’s feedback will have the strongest impact

What may seem like conventional wisdom rarely gets executed in practice. Citing research from Stanford University and the University of Michigan, Daniel Pink explains that people often rate something higher if they know it’s the end. They rate their day better if they know it’s the last day of class, or rate a snack better than prior snacks if it’s the last one. If you want feedback to stick, deliver the most important information at the end. The last bit of information will be the most impactful to the developer.

As a reviewer, if you have a constructive commentary for a developer, don’t water down the significance of the change towards the end of a thread. Remember that the last piece of information delivered will create the strongest impact. If you are batch processing your code reviews by reading through multiple proposed file changes during one block of time, make sure to save the most important change for the very end.

And if you want to vocalize your appreciation for a job well done, the compliment will be strongest if it’s delivered at the end.

5. Frequently check in on how a colleague is approaching a problem — switching costs increase the longer you wait

Asking someone to change methods is hard. Daniel Kahneman, author of Thinking, Fast and Slow writes, explains that individuals value the psychological safety of the status quo and what they currently own, more than the potential upside of switching behaviors. It’s the reason people tend to hold onto shares in a losing company longer than they ought to, and are hesitant to switch passwords even when prompted by a security expert.

Reviewers should keep this psychological tendency in mind when providing feedback to developers. Asking a colleague to make a radical departure from the methods they traditionally use to solve a problem can lead to a psychological backlash creating internal conflict. Even if your preferred method as a reviewer is truly better, it will be much harder to convince a developer to switch at the end of a process than at the beginning.

Asking a developer to approach a problem differently at the beginning of a process can lessen the psychological burden of switching gears. This is why it’s important to check in even during a work in progress or when a function is mapped out, before the approach is decided.

Managers can also attempt to work within the context of how a developer approaches a problem rather than presenting an alternative perspective as a radical departure from the status quo.

All Remote: Documenting your code is now essential. There is a better way. (Part 4)

Claudio Pinkus — Wed, 20 May 2020 14:48:36 +0000

Introduction

In Part 1, we discussed the personal and human factors affecting all of us during the COVID-19 pandemic. In Part 2 of this series we talked about how a combination of cultural and technology factors has traditionally led to insufficient collaboration among developers. In Part 3 we discussed how transparency needs to turn into visibility in order to create team alignment and boost velocity and productivity. We turn now to documentation as a tool to improve remote developer performance.

Documentation has been a source of frustration and conflict in software development for many years. The problem is, fundamentally, that many developers don’t document their code, or do so poorly. As a result, other developers who need to understand the code they are utilizing or changing spend many frustrating hours addressing this shortcoming. Understanding code can take as much as 10X the amount of time as writing new code.

Why don’t developers document their code?

There are many examples of articles and posts that discuss this question. For instance, this article in Infoworld from 2012 asks “Why don't programmers document? Real programmers don't document is an old chestnut of hacker machismo, one that some coders have sadly taken to heart,” Infoworld states. Their answer might reflect a nugget of truth, but is by no means a universal explanation nor a solution. In a post in 2018 Tomer Ben Rachel argues that “The main reason code goes undocumented is because of time. When developing a feature that needs to be completed within a certain time frame, rarely do we have a moment to stop everything and focus on documenting our code.”

In an all-remote world, documentation is one more essential tool to sustain team alignment. This is a great moment to revisit how we think of documentation and its value. The good news is that there is a better way.

The dawn of On-Demand documentation

At CodeStream we have been working to improve internal documentation practices for over two years. Given that so many fast-moving organizations don’t produce much useful documentation, and that surveys show that less than 15% of developers use internally generated documentation in their work, we believe in on-demand documentation. What does this mean?

When a developer implements a new component or module, instead of trying to figure out in advance what others may not understand when they encounter the code in the future, CodeStream allows the developers using that code to more easily ask questions, and pull the information from the authors. We have implemented an in-editor interactive FAQ approach that captures the question and answer interaction and attaches it to the code it refers to. So not only do the missing pieces get filled in to solve the immediate need, the discussion is saved alongside the code for the benefit of the next developer who consumes the component or module.

Bringing it back to the IDE

Until now, information about your code that explains how it all works has been fragmented, spread out in a variety of different tools and systems. Finding the right information is quite time-consuming, and sometimes impossible. By tying it all back to the IDE and, specifically the code it refers to, documentation emerges as the byproduct of the interactions that take place every day among developers in Slack, Jira, GitHub and other systems. CodeStream inserts itself in the workflow to capture and organize the information so that it becomes accessible and actionable in your editor. Given that the Number 1 Challenge for developers today is sharing knowledge, CodeStream sits exactly where the intersection of documentation and collaboration lies. Collaboration solutions that are specifically designed for developers will become the foundation of useful on-demand documentation.

The future of documentation in On-Demand

The future of software development will include a higher percentage of remote co-workers and teams. We have seen that an all-remote approach requires flexibility, the right collaboration tools, transparency and visibility. It also requires a new approach to documentation if we are to make all-remote work as effective as sitting side by side in an office. Adopting an on-demand approach to documentation solves two problems we have been wrestling with for a long time. It relieves developers from investing time and effort trying to figure out what others might not understand, and it improves knowledge sharing not just among two developers but for the organization as a whole.

All Remote: Transparency becomes essential when working all-remote (Part 3)

Claudio Pinkus — Wed, 20 May 2020 14:41:16 +0000

Introduction

From a technology perspective, until recently it’s been surprisingly difficult to carry out simple tasks like asking a question about code you are viewing in your editor, but don’t understand. If you are among the developers who use tools like Slack or GitHub to discuss code, there are some significant limitations in both, but for different reasons. Developers often turn to Slack to ask ephemeral questions about code that’s unclear, but this involves copying and pasting from your IDE into a channel, and having to then recreate the whole context you just lost in order to explain to the recipient what they are actually looking at. Code reviews are often conducted In GitHub, where the context is more clear, however, you are limited to discussing only the changes that are part of that PR. What if you have questions or a suggestion about another part of the code that is not changing?

Here we will focus on another aspect of remote work. Before your team went all-remote, it was relatively easy to keep informal tabs on what everyone was working on. Just looking around you, could see who is at their desk or in a meeting, or who moved a task on a board. Gone is the physical tap on the shoulder to ask a question or bounce off an idea. In an all-remote world, there is a need to become more transparent in order to improve collaboration, perhaps to demonstrate to your boss that you are actually working while at home, and most importantly, to improve performance and code quality for your team and your company.

What is transparency in software development?

One way to think of transparency is to consider it a philosophy, or a point of view. It implies openness, communication, and accountability. Transparency is operating in such a way that it is easy for others to see what actions are performed, and how they are performed. The benefits of transparency were well understood long ago. As explained by Nathan Donaldson of Boost, there are many different dimensions to transparency. For a manager, it might mean knowing the status of a project. For a developer it might be seeing work in progress on a board. In both cases, it’s about producing the best product with the lowest risk. This chart from Boost, who specialize in Agile risk management, illustrates its benefits:

From Transparency to Visibility

Kanban-style boards have been popular in software development for a long time. If you used to rely on a physical board to have visibility of the state of a project, in a remote team that becomes impractical. Some software tools, like Trello, implement the methodology of a kanban board and give you task level visibility of what your teammates are working on. That is very useful and quite adequate for improving visibility in a remote team. However, the value of radical transparency becomes more evident in a remote environment. As communication is a bit harder, it’s easier to make mistakes or incorrect assumptions.

As described by Matthew Bellows in this post by First Round Review, there is a strong case to be made for Radical Transparency among startups, which is likely to apply to companies of all sizes. Matthew says: “Whether you’re starting from scratch or looking to make your existing culture more transparent, start by building it into the tools you use every day. Make the executive team’s calendars visible internally, for example, so everyone can see who’s in a given meeting or when colleagues are available.”

That is why at CodeStream we have been working on giving development teams the tools they need to increase visibility at a granular level.

The networked IDE comes of age in a remote era

Developers tend to choose their IDEs individually in a BYOD world. In any given team you might find some using VS Code, others IntelliJ, a third group Atom or pycharm. One of the best ways to increase granular visibility is to connect your teammates’ IDEs to each other. That is exactly what we have done at CodeStream. We just introduced Live View, a new feature in our collaboration platform that allows admins or any developer to see a live snapshot of what everyone is working on. Specifically we show each user’s name with a list of the repositories in which they have made local changes (i.e., edits that haven’t been pushed). When you hover over a repo entry, you can see the actual files that have changed, as well as the number of additions and deletions, like this:

Note also the warning sign indicating that Peter may have a potential merge conflict in the “gore” repo. He can then contact whoever is also working on that file in “gore” and resolve the issue before it becomes a painful process to unwind, or to ensure that they aren’t duplicating work.

Documenting code is a great way to increase transparency

Software development projects are notorious for their lack of useful documentation. When working remotely, documenting software becomes increasingly important as informal communication decreases while the increased friction can slow things down. Yet, asking developers to document their code may not be the best answer.

In Part 4 we will describe how we have tackled the documentation issue at CodeStream with a radical idea. We capture the interactions that take place every day among developers in tools like Slack, Jira, and GitHub and turn them into nuggets of wisdom that explain how the code works.

Developers Must Choose Collaboration in an All-Remote world (Part 2)

Claudio Pinkus — Wed, 20 May 2020 14:35:57 +0000

Introduction

In Part 1 of this series, we talked about how we need to take into account personal and human aspects of our all-remote life that are not about just business or our careers. We also pointed out that being a software developer is a privilege, and that we have the opportunity to contribute to society while sitting at home and applying our knowledge and creativity. Challenging times are often the right moment to re-examine what we take for granted. We believe there is room for improvement in our software development processes, and now is a good time to start. In this article, we will begin to look at what drives dev team performance, and how our culture has been resistant to adopting a more collaborative approach for historical and competitive reasons. We will describe ways in which we, at CodeStream, have learned to tackle these issues and the impact we are seeing as a result of our approach.

We don’t collaborate enough

Over the past two years, we have talked to about 2,000 software development teams in an effort to understand how their toolset, their workflow, and the opportunities for performance improvement. If you are like over 80% of the teams we talked to, this is what your toolset and workflow look like:

The team plans the sprint on a Monday and developers mostly stay focused on your assignments until the end of the sprint, usually a week, with relatively little collaboration until the code is done.
You ask questions ad-hoc, sometimes to the developer sitting next to you, sometimes on Slack or Microsoft Teams. Mostly, though, you just try to figure it out on your own. There are no incentives to collaborate, other than at code review time.
You use GitHub, GitLab or Bitbucket for version control and code reviews.
You assign work through Jira, Trello, Asana, or something like it. Most often, all assignments start in your task management service. You complete your assignments largely without collaborating with anyone on your team.
Overall, you have little visibility of what your teammates are working on at any given moment.

If this seems right, it all makes sense because we are so used to the process. What parts of this can be improved upon in an all-remote mindset and context? To start with, how often do you check with your team or your reviewer on whether the feature you are starting on is on the right path? How often do you suggest a change to a teammate to improve code quality? If the answer is rarely, or even just once or twice a day, you are not optimizing your process for collaboration purposes. In particular, if you are used to resolving issues by just tapping someone on the shoulder or asking out loud in a room with your teammates, a new approach is required. Let’s tackle each of the bullets above through a collaborative lens.

There is no shame in asking

Most developers take pride in solving problems on their own. Perhaps it’s a badge of honor, or given the fact that we live in a competitive environment, it feels like asking will reveal some weakness on your part. As a team, at CodeStream we have created incentives to ask more questions more often, and we reward this type of exchange in public, reporting participation on our weekly all-hands. A customer of ours is planning on tieing part of the developers’ bonuses to the collaborative contributions made, whether asking a question or providing an answer. You should consider how your organization can promote more openness in code discussion.

Still, in a remote setting, the tools commonly used today for code discussion are particularly sub-optimal. Using something like Slack or MS Teams results in ephemeral exchanges that do not add to the collective knowledge and require significant effort to provide the context that was stripped away by copying a code block and pasting it into a chat stream. Further, since the question itself is likely to quickly scroll off the screen never to be seen again, these solutions don’t offer the persistence and accessibility needed in an asynchronous remote world.

We built CodeStream to solve this by attaching questions and replies to the code block(s) they refer to and then sharing this in Slack, MS Teams or email to leverage your existing communication tools. CodeStream is the in-editor bridge that makes these discussions more frequent and more useful to the whole team.

The pull request is great. For code reviews, we can do better.

Virtually every modern development team we have talked to since 2019 performs code reviews using the built-in tools of GitHub, GitLab, and BitBucket. Large organizations like Google and Microsoft have developed their own tools to conduct code reviews that are not PR based. At Google, they have standardized on a uniform toolset with a strong focus on speeding up reviews by making them as small as possible. Google reports that its average code review is just 24 lines of code and gets turned around and into production in 4 hours or less.

We believe they have the right philosophy and the right results. There are many benefits to small and fast reviews. Productivity increases, frustration is reduced, small mistakes don’t turn into large messes, and perhaps most importantly it allows larger teams of developers to weave changes together with minimum conflict. What does it take to make this happen in your organization? Pull requests don’t make it easy to review code. To start with, reviewing code in a browser instead of the IDE introduces the same type of context problem we discussed above with Slack, an unnecessary context switch. In addition, much frustration and effort can be eliminated by asking for reviews early and often, even on uncommitted code.

At CodeStream, we have built a solution that makes this super easy. We just package every change made by a developer in their editor, organize it and size it, and let the developer decide which parts to submit for review. The reviewer can then see all the changes in context, in their editor, attach comments as necessary, and approve or reject the work on a file by file basis. Our team is now conducting 10+ reviews per day per developer, and our velocity has increased by over 20% since we started this process.

Transparency and visibility

Working remote brings new challenges in the area of visibility. Not only can we not see each other in the office anymore, but it’s harder to work towards alignment without the right tools. In order to get the right visibility, we must start with a philosophy of transparency. In an all-remote world, we must choose to let everyone see what we are doing because without it there is too much friction and we lose traction. GitLab has famously included Transparency in their Six Values. How do you implement transparency in your development process to get everyone on the same page? We will tackle that in part 3 of this series.

We are all Remote Developers: Working From Home (Part 1)

Claudio Pinkus — Wed, 20 May 2020 14:29:38 +0000

Introduction

This is the first article in a four-part series dedicated to helping software developers, managers and organizations adapt to the pandemic emergency and become all-remote. In this first article, we will focus on the basics. There are many lists available discussing the right toolset and the behavioral changes necessary to be an all-remote team or organization. This article is not about that. Here we will dive into the human aspects affecting all of us, and address some of the ways in which we can turn this unfortunate event into an engaging learning experience for ourselves, our team and everyone we interact with.

The world during the pandemic

First, a personal note. I am 63 years old, suffer from high blood pressure, and I am scared and concerned, like everyone else who knows what’s happening. You already know that there is much we don’t know. This event will affect virtually everyone on the planet in one way or another, and many factors, including our emotional reaction to what’s happening around us, will make the situation very challenging and potentially extremely challenging, both at home and at work. We are all distracted from our business and professional obligations for good reasons, and we need to allow for a measure of distraction as there will be many moments of intense focus on the worries we are facing.

In the context of work in particular, which is the general theme of this series, I urge all of us to practice extreme kindness and understanding during these difficult times. In terms of our professional activities, there will be delays, confusion, flared tempers, and a full range of emotions on display as we tackle working together remotely under these circumstances. Since we are mostly working from home, work-related stress can also spill over into our family life with no clear escape valve. Rather than inflame conflicts, it’s a good time to take a step back and diffuse situations. Just like the stock market has a fuse to avoid extreme buying and selling situations from getting out of control, we should all recognize that diffusing and restarting is the best path forward for both personal and professional outcomes.

The privilege of being a software developer

Software development is a privileged profession. Not only do we get to build magic, but we can do it from anywhere. With an Internet connection, we can stay professionally connected and productive. Programming is intellectually engaging, so it’s relatively easy to lose yourself in the problem you are trying to solve, providing both a needed distraction and a real purpose. Developers usually work as a team, so you feel like you are part of something bigger than yourself, which also helps with motivation, engagement and emotional balance. So, while we cannot set our worries aside, we can spend part of our day focused on building something that matters now and will matter in the future.

Take a moment every day to be thankful for this privilege. In good times, the ability to stay home with your family while you work is a nice-to-have. In the current situation, all these amazing technologies we have been building in the last 30 years are holding us together, allowing us to stay productive, and support the creation amazing new products and services that you will be part of. What a great opportunity.

Every developer is now a remote developer

At CodeStream, we have been remote since Day 1. In fact, our team has been working remotely for more than 20 years, over the course of four different startups, since before Zoom or the iPhone even existed. Because we have built a strong culture around remote, we have never felt disconnected or lonely. Because we understand that not everything about working remotely can be accomplished by using Zoom alone (by the way, we love Zoom), we have always worked extra hard at forging the bonds that sustain us during hard times.

Over those 20 years we have had several hard moments, even if they do not seem that hard by comparison in light of the moment we are living through now. We have been together through deaths, divorces and illnesses, and we have always found a way to bring the human element back into the professional environment to make us stronger and more resilient as a team.

This is not the time to move fast and break things. This is the time to stay focused on doing the right thing, helping others, and finding strength in our common goals.

Let’s get to work

My next post will describe in detail the way our development team is working, including tips and tricks we have learned over the years. We believe there are many aspects of communication, integration, transparency and knowledge sharing among software developers that could use some improvement, and the fact that we are all remote now is an opportunity to improve on those deficiencies. In the meantime, if you would like a preview, here is a short post that you might find helpful.

The Connected IDE: A communication-first approach drives collaboration (Part 2)

Claudio Pinkus — Sat, 16 May 2020 15:33:36 +0000

Introduction

In Part 1 of this series we touched on the evolution of IDE from a personal, standalone tool to a connected and networked hub of all things code. We explained how connecting your IDE to your teammates’ simplifies communication and collaboration with two specific use cases: Discussing code in general, and performing code reviews right in your IDE, eliminating the context switching and improving knowledge sharing.

In this post we will expand this to additional use cases and show how the Connected IDE is the most important step towards team collaboration in a world where we are all remote developers.

What is collaboration anyway?

There are many flavors of collaboration platforms and tools for developers, and many permutations through extensions. In the context of making your IDE more connected, we look for collaboration to enhance velocity and value for the team. In a post updated on November 24, 2019, Geoff Stevens writes about How to collaborate like a pro in VS Code. Since VS Code is today the most popular modern editor, we will focus on it as an example, but the analysis applies to much of the collaboration approach out there.

In the post, Geoff looks at a list of VS Code extensions that bring collaborative features into the editor. These include, among others:

Microsoft’s own Live Share that “eliminates the friction of coding together by letting you collaboratively edit, debug, and fix code in real-time without leaving the comfort of your own VS Code setup,” according to Geoff. Live share is pair programming inside VS Code, and provides an experience that is reminiscent of screen-sharing, but specifically for developers.
CodeStream, which “allows you to comment, ask questions, and have discussions across your codebase from within VS Code.” Note that CodeStream now also allows you to perform code reviews in your editor.
The Jira extension for VS Code gives you the ability to “view, search, and filter issues in Jira inside VS Code.”
GitHub Pull Requests that helps you review and manage GitHub pull requests right inside VS Code.

We believe that collaboration starts with communication between developers. Through that lens, only Live Share and CodeStream are actually delivering collaboration, while the GitHub and Jira extensions serve only to reduce friction for the individual developer by reducing context switching. We believe collaboration is a communication-first endeavor. The ability to view or reference other content inside my IDE makes it easier for me to collaborate with my team, but only in communicating am I actually explaining my intent and resolving conflicts, misunderstandings or misalignment. A communication-first approach drives velocity and code quality.

Code needs to be a first class object in communication

In order to reduce friction and simplify communication about code, the code itself needs to be a first class object in the communication exchange. In part 1 we discussed the difference between a Personal IDE and a Connected IDE approach to asking a question or performing a code review. Here we will present a couple of use cases that illustrate how a tool like CodeStream allows code to become a first class object because your IDE is now connected.

Suggesting an improvement

Personal IDE: You come across some code that you believe could use some improvement. You don’t want to take this on as a project, nor do you want to change someone else’s code without communicating with the author. You copy and paste the code in question into Slack or MS Teams, explain the context (repo, file, line number, etc.), type the code you suggest replacing it with, and explain why you think it’s a better approach. Upon receiving your suggestion, the author needs to locate that code in their IDE, review your suggestion, get back to Slack, discuss it with you, copy and paste the final suggestion (if modified) into her editor and push it. If this happened once, perhaps the friction would be tolerable. But there is just as much friction the second time you have a suggestion, and a third.
Connected IDE: You see code you believe could use some improvement. You make your suggested change in your IDE. Then you highlight the code block in question and add a comment in CodeStream such as, “is it safe to short-circuit the loop here? It would make this function much more performant”, like this:

When the author gets the notification, she can just do a diff in her IDE and apply the patch if she finds it useful, like this:

Connecting related code:

Personal IDE: Let’s say you want to point out to your teammates that different parts of the code you are writing are related. Perhaps you want to indicate the part of a React component that isn’t interacting with your stylesheet in the way you would expect. You would choose a file, jira ticket, or slack thread to communicate this outside your IDE and assemble there the list of permalinks that point to those code blocks in the different files. Whenever you or anyone on your team wants to make a change, you would have to try to find that external resource with the permalinks.
Connected IDE: If you want to connect different parts of the code and share that information with your team, you can just make a comment on one of the codeblocks and add the different ranges in other files and even other repos that are connected to that original range, like this:

The Connected IDE enables knowledge sharing

Coding Sans conducts a Development Trends Survey every year, and for the past two years the #1 challenge for developers is Sharing Knowledge. It’s very telling that the issue of knowledge sharing remains so challenging. The personal IDE, where each individual developer produces code remains an island detached from colleagues and teammates, so extra effort must be applied to share information about the code being produced. We already covered the fact that documentation is not common among development teams. The Connected IDE provides an opportunity to finally address knowledge sharing in an effective and ubiquitous way.

The Connected IDE is the gateway to increased developer collaboration (Part 1)

Claudio Pinkus — Sat, 16 May 2020 15:29:38 +0000

Introduction

Like the standalone PC’s of the 1980s, the personal IDE remains an island detached from the opportunity to improve collaboration for the development team and the company as a whole. A new era of connected IDEs is coming that does not require you to leave behind the IDE you love. Using modern plug-in technologies, your IDE can begin to evolve towards a truly Integrated Development Environment that will make collaboration easier while improving code quality.

History

In the beginning of the personal computer revolution, circa 1975, the IDE was invented. It was called Maestro I and it was the first “modern” development environment. The Integrated aspect of the IDE refers to the combination of a source code editor, build automation tools and a debugger. Since then, a plethora of IDEs have been developed ranging from VI and VIM to Emacs, Visual Studio, Sublime and VS Code. The term has evolved to refer both to the source code editor as a standalone tool, as well as the more complex environments that integrate multiple tools.

A more modern concept of integration refers to the ability of an application to connect to another, typically developed by another entity or company. For instance, the Jira Integrations page displays a collection of hundreds of third party applications not produced by Atlassian that connect through APIs to Jira. Let’s explore now the state of the IDE world.

The modern Connected IDE is taking over

Much has changed in the last 5 years in the IDE world. When Stackoverflow asked developers to select their favorite editor/IDE in 2015, these were the results (Note that you can vote for more than one editor, so totals can add up to more than 100%):

Sublime and NotePad++ were leading the pack, while Atom, a product of GitHub was just emerging as the first truly extensible editor. Atom was built on Electron, and was touted as A hackable text editor for the 21st Century.

In 2017 the state of the IDE had already changed significantly:

While the question itself had changed (now segmenting web/desktop/sysadmin), the top dog was now Visual Studio for both Web and Desktop development, while Atom moved up to 20% and IntelliJ to 23%. Visual Studio and IntelliJ charged for their editor, while Atom was free to use and Open Source.

By 2019, the picture had changed again, now with a new leader from Microsoft:

Visual Studio Code, an Electron-based Open Source free editor is now the #1 IDE in the world, and it’s very extensible. Atom has fallen off and will probably continue its decline in 2020, now that GitHub (publisher of Atom) is also owned by Microsoft. All modern editors now support plug-ins, and therein lies the collaboration opportunity: The connected IDE.

From the Personal IDE to the Connected IDE

Most developers today continue to code in a Personal IDE mode. When it’s time to ask a question or have someone review their code, they move it over to a different environment, outside their IDE, losing context and unnecessarily introducing friction. This is a big deal because quality and productivity suffer. At CodeStream, we have interviewed over 2,000 development teams to find out how they go about producing code. Let’s take a look at two scenarios that benefit drastically from having a connected IDE.

Asking a question:

Personal IDE: Before we all began working remotely, a tap on the shoulder was probably the most common way to ask a question. Now, if a developer has a question, she will copy and paste the code in question into Slack or MS Teams (or even take a picture of their screen!), explain the context (repo, file, line number, etc.), find the right person or channel to ask, and when she gets the answer, that interaction will soon scroll off the screen in an ephemeral chat stream that will not contribute to sharing knowledge within the team.
Connected IDE: She can just select the code in question, comment on it (like you do in Google Docs), select who to share it with (the context is self-evident here, so no explanation needed), get the answer, and everyone on the team can now benefit from that knowledge, like this:

Requesting a Code Review:

Personal IDE: Most developers use GitHub, GitLab or Bitbucket to request a code review. That is also where the reviewer performs it. It may feel like that is the right environment for this discussion but in fact, it introduces multiple points of friction that make code reviews slower and harder. 1) It takes you out of your natural coding context by moving the discussion to a web browser, where understanding code is unnecessarily difficult. Why would you want to limit the amount of visible code to just a snippet? If you need to get more context, you need to go back to your editor. And to know what’s happening, you still need a notification tool, like email or Slack. In addition, 2) It forces the author of the code to predetermine what should be reviewed by establishing the PR as the earliest possible time for a review. What if I just want some feedback on WIP or uncommitted code?
Connected IDE: As your IDE is already connected to your reviewers’ IDE, the steps are simpler and shorter. First, you do not have to switch context. Your IDE knows exactly what changes you have made. Some may be ready for a formal review, others just for a quick check on general direction. Your IDE can package up every change automatically, ask you if you want to remove any changes from the package and make the request for a review to your preferred reviewers, notifying them through Slack, MS Teams or email, or even easier, just seeing a badge in your IDE letting you know that a review is awaiting. The reviewers can perform the review in their connected IDE and see exactly the state of the code in the author’s editor. The reviewer can comment, suggest, and question with full context. The review can be completed even before a PR is created. Easier and faster. Like this:

In the future, every IDE will be Connected

Atlassian, one of the world’s largest development tool companies, believes that teams are the foundational unit of the company’s culture. So strong is their belief in teams that the stock ticker for the company is in fact TEAM. But culture is only the first step in enabling teams to optimize their performance. As we will see in the next post, the Connected IDE has a big role to play in fostering a positive and productive team environment.

CodeStream Case Study: Hearst Communications

Michael Gersh — Mon, 11 May 2020 14:58:02 +0000

Overview of Hearst Communications

Hearst is a leading global diversified media, information and services company. Its major interests include ownership in cable television networks such as A&E, HISTORY, Lifetime and ESPN; global financial services leader Fitch Group; Hearst Health, a group of medical information and services businesses; transportation assets including CAMP Systems International, a major provider of solutions for managing maintenance of jets and helicopters; 33 television stations which reach a combined 19% of U.S. viewers; newspapers such as the Houston Chronicle, San Francisco Chronicle and Times Union; more than 300 magazines around the world, including Cosmopolitan, ELLE, Men's Health and Car and Driver; digital services businesses such as iCrossing and KUBRA; and investments in emerging digital entertainment companies such as Complex Networks.

The Challenge

Heart’s front-end site rendering team of 20 engineers builds and maintains a platform that powers the customer-facing experience for 175 online magazines. The team uses multiple tools for communicating and sharing information, including Slack, Jira, GitHub pull-requests, and email. In addition, the team is mostly distributed across the US, and from time to time they work with international teams as well, where the ability to share information contextually is even more important.

As the team became larger, important conversations about the code were scattered across their various development tools and systems. It was becoming increasingly common for team members to misunderstand a key decision because they could only see part of the discussion, or altogether miss key conversations and information exchanges. They needed a solution to consolidate team communication and make information about the code readily accessible to all team members. Enter CodeStream.

The Hearst Front-End Site Rendering team derived the following benefits from CodeStream:

The team uses CodeStream as the central communications hub for their several development tools and systems.
The speed of getting questions answered has greatly accelerated. Previously, an engineer would have to go to the source code to share or understand context. Because CodeStream links comments and discussion to the code they refer to, the friction and overhead are completely eliminated.
CodeStream’s latest in-IDE code review feature has given the team a fast and easy way to request early feedback on new code, so work-in-progress is being reviewed even before being committed or pushed. This reduces the chances of a team member going down a coding rabbit hole that could cause painful re-work later in the cycle.
Overall, the team is better aligned, communicating about the code earlier, and code quality has improved.

The Bottom Line

“Great communication is essential for any software development team, but as your team grows, sharing key information about your code simply becomes harder to do. Important conversations become fragmented across different tools and systems, and for teams with remote workers, this is even a bigger problem. For our team at Hearst, CodeStream is the missing tool that helps engineers discuss and review code earlier and more often, and it saves that information alongside the code where it matters most. No tool is perfect, but I give CodeStream 9 out of 10.”

‍- Alfredo Lopez, Director of Engineering, Hearst Communications