GitLab Commit 2021 - Upgrade your development workflow with interactive code maps

Earlier this week, I gave a talk at GitLab Commit 2021 about how we can build our understanding of code, share that knowledge with other people, and use new tools for guidance and navigation as we create, fix and improve code. If you weren’t able to attend the event, don’t worry! I’m going to recap my talk here. If you prefer to watch vs. read, scroll down for a 14 minute video of my talk.

Here’s the problem I outlined:

Acquiring knowledge about code is hard. And communicating it across teams is even harder.

So when we make structural changes to code, I think it’s important to pause for a minute and confirm our assumptions before we start changing things. Getting extra context and getting oriented is really important when making performance changes, refactoring or fixing tough bugs -- because navigation of code becomes less apparent when we make these types of complex changes.

This is particularly relevant in DevSecOps, because security has specific skill sets and values. Bringing security into DevSecOps requires everyone to learn more about people in adjacent roles, and learn a bit of their language and value system in order to collaborate and share context efficiently.

Here’s the example I shared:

Take the lifecycle of a bug fix, a basic communication process that happens every day between 3 different people in different roles. You’ve got:

The person reporting the bug (e.g. another developer, a QA tester or security tester)
The developer fixing the bug
The code reviewer

There are 2 handoff stages here: from the bug finder to the developer, and from the developer to the reviewer. At each stage, a knowledge transfer needs to happen between people with very different experience levels with the code in question. In fact, it’s possible that none of these 3 people really know this particular area of the codebase that well. But they all need to work together to get a code change written, reviewed and approved.

The bug finder knows that the dev team wants as much descriptive information about the bug as possible -- what the tester was doing, what they typed in, what buttons they pushed, what they saw, etc. This description can be accompanied by some screenshots and for UI bugs, this works great. But what about bugs in application behavior, where it’s the backend that’s misbehaving? Maybe the user is presented with inaccurate information or data belonging to someone else! Or they expect to go to page X but end up on page Y. What then?

Here’s the solution I proposed:

As a developer, wouldn’t it be great if the bug finder could send you the equivalent of a screenshot, but of the backend internals? How about a map of code paths, including all the dynamic and complex stuff like HTTP requests, caching, user session interactions, security and SQL?

This is all possible with code maps. And by code maps, I mean a visual presentation of code (other than the code as text) that makes a design aspect of the code easier to understand.

Making code maps is possible with AppMap, a free, open source tool that makes runtime recordings of code. AppMap works equally well with large and small projects, web applications, and microservices. It captures all the information I described above, and bundles it into a portable JSON format. It’s also easy to write programs that process, analyze and display AppMap data.

Quick sidebar: Last week we released a GitLab integration for AppMap! Now you can upload AppMaps to the AppMap Cloud and log in with your GitLab account. You can also attach links to AppMaps stored in AppMap Cloud to your GitLab merge requests. Here’s a short demo video if you’d like to see this in action.

Here’s the demo I gave:

In my talk, I showed how to use AppMaps to transfer information about bugs from testers to developers, and from developers to code reviewers. Start watching at the 5:00 mark in the video to watch the demo.

Next steps you can take:

If you’d like to try using code maps to accelerate code understanding and improve communication with your team, you’ll need to:

Install AppMap for VSCode or JetBrains
Install and configure the AppMap client agent for Ruby, Python, or Java
Show your dev team or pen testers how to run the app with AppMap enabled, and use the AppMap browser extension to record what they see and do
Show everyone how to upload and download AppMaps - from your own internal repository, or from AppMap Cloud