Add AppMaps to a code issue

Introduction

When developers start working on a new code issue, their hardest job is to build an accurate mental model of the existing code design. So, when you define an issue, such as a bug report or feature request, it’s important to provide as much context and supporting information as you can.

When attached to an issue, AppMaps provide a wealth of helpful context around the bug or feature being described. AppMaps provide both high-level and low-level information, and they are also searchable and interactive.

In the context of a bug report, an AppMap provides the full context around a particular problem. It captures the exact conditions and call stack that led to an unwanted behavior. Developers can use this information to quickly hone in on likely trouble spots.

For new feature work, AppMaps can point out areas of particular interest and crucial code and data flows. This is a powerful way for a developer who’s experienced with the code to make suggestions about how the implementation might proceed.

So when creating an issue, think about key factors that the developer will need to understand. Then create and attach AppMaps to the issue which demonstrate these key factors, and if possible, suggest productive ways to proceed.

How it Works

An AppMap is a recording of code execution. Therefore, when creating an issue, record AppMaps of the code that provide detailed information about it. For bug reports, make an AppMap of the bug happening in the app, either by running a test case that reproduces the issue, or by running your app and using an alternative AppMap recording method. For feature requests, record the test cases that are related to the new feature. For example, if the issue requests a new authentication method, record the existing authentication methods. If it requests a new HTTP status code, record the existing code paths and status codes. If the code base is well covered with automated tests, this is as simple as identifying the most relevant tests. Otherwise, again, you can use an alternative recording method. Either way, you are doing a great service to the developer who will pick up the issue - because you’re making it easy for them to head in the right direction.

Once you’ve got the right AppMaps, you just need to attach them to the issue. You can do this by attaching AppMap files directly to the issue, or by uploading AppMaps to the AppMap Cloud and then placing links in the issue. Details of both approaches are discussed below.

Step-by-step

Bug report - Reproducing the bug

When reporting a bug, provide an AppMap that reproduces the bug. This will be incredibly helpful to the developer who works on the bug. The best way to create an AppMap of a bug is to record a test case which reproduces it. Alternatively, you can use one of the other recording method. For example, if you can reproduce the bug through the app UI or API, you can record the server as you step through the scenario.

Feature request - Record useful, “nearby” test cases

When submitting a new feature request for an area of the code that you know well, you can help other developers by including AppMaps of related functionality. For example, if you want to enhance a particular page or API function, provide AppMaps that show how the page or function currently works. If there are particular security or performance considerations, provide AppMaps that show how those requirements are handled in similar situations.

Opening an issue

Open the issue in your issue tracking system as you normally would.

Attaching an AppMap file

The simplest way to add an AppMap to an issue is to insert the AppMap JSON file as an attachment. You can reveal the location of the AppMap file using the AppMap extension for your code editor.

:warning: Files with JSON extension cannot be directly attached to GitHub issues. We recommend that you zip the the .appmap.json files prior to attaching them.

VS Code:

  1. Right click on the AppMap editor window tab and pick “Reveal in Finder/Explorer”
  2. A Finder/Explorer window opens with the AppMap file selected
  3. Right click on the file and compress/zip it
  4. Attach the zip file to the code issue

Attach AppMap to a GitHub issue

Linking to the AppMap Cloud

When the relevant AppMaps have been uploaded to the AppMap Cloud (manually or in an automated CI/CD workflow), you can link to them directly from your issue tracking tickets.

  1. Open the application and the applicable mapset in the AppMap Cloud
  2. Open the AppMaps tab and search for the AppMap name
  3. Open the AppMap, click on the “Share AppMap” icon and copy the shareable link
  4. Insert the link into the issue ticket.

Linking to AppMap Cloud gif

Downloading and installing the AppMap

AppMap files attached to issues can be easily downloaded by others to their local project folders and opened in a code editor with the AppMap extension.

Download as attachment

AppMaps attached to tickets can be directly saved as .appmap.json files into project folders and opened in the code editor:

  1. In the ticket page, locate the attachment
  2. Save the attachment to your project folders. If it is a zip file, righ click and unzip it. If it has any other extension, save it as a .appmap.json file
  3. Open the downloaded file in the code editor.

Download as an attachment gif

Download from AppMap Cloud

Public AppMaps stored on AppMap Cloud can be downloaded and opened in the the code editor easily:

  1. Open the AppMap in AppMap Cloud
  2. Click on the “Download” icon in the top right corner of the page
  3. Open the downloaded AppMap file in your code editor.

Download from AppMap Cloud gif

Using the AppMap to solve the problem

Follow the Debug code with AppMaps guide for tips on how to best use AppMaps when solving difficult problems.

Verifying a fix or feature with AppMaps

Once you’ve implemented your code changes, you should verify the correctness of your solution by making a test case that asserts all the proper behavior. You can provide AppMaps of your test cases to a code reviewer by attaching them to the pull/merge request. You can attach an AppMap to a pull/merge request using the same procedure that you use to attach it to a task or issue.


Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!