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.
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.
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.
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.
Open the issue in your issue tracking system as you normally would.
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.
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.
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.
AppMaps attached to tickets can be directly saved as
.appmap.json files into project folders and opened in the code editor:
Public AppMaps stored on AppMap Cloud can be downloaded and opened in the the code editor easily:
Follow the Debug code with AppMaps guide for tips on how to best use AppMaps when solving difficult problems.
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.
Identify the N+1 anti-pattern in Java.
Identify the N+1 anti-pattern in Rails.