feat(suspect-commits): Add more information on creating code mappings (…

…#8155)

Code mappings are more complicated than the current docs make it out to seem, so this adds more in-depth info on how to decide what values to use for the code mapping.

Importantly, this also calls out that this case does not work for platforms with package names. I will follow up with additional docs on what to do for those platforms.

src/docs/product/integrations/source-code-mgmt/azure-devops/index.mdx

@@ -119,11 +119,33 @@ Stack trace linking takes you from a file in your Sentry stack trace to that sam
    - **Project** (required): This is the Sentry project.
    - **Repo** (required): This is the Azure DevOps project associated with the Sentry project above. If you have more than one Azure DevOps project being used per Sentry project, you'll need multiple code mappings.
    - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
-   - **Stack Trace Root** and **Source Code Root** (optional):
-     - If the file path in your Sentry stack trace frame matches the path to your source code, you don't need to set these values.
-       - For example, if everything after the branch (`main`) matches the file path of `code.py` using a source code path of `https://MeredithAnya.visualstudio.com/testing/blob/main/code.py`, you don't need to set either `stack trace root` or `source code root`
-     - If the file path in your Sentry stack trace frame doesn't match the path to your source code, you will need to replace the `stack_root` part of the file path with your `source_root` to make the file path match the source code path.
-       - For example, to get `src/code.py` to match `code.py` when the source code path is `https://MeredithAnya.visualstudio.com/testing/blob/main/code.py`, change the `stack trace root` to be set as `src/`, and leave `source code root` empty.
+   - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values.
+
+#### Stack Trace Root and Source Code Root
+
+<Note>
+
+The following information is only valid for platforms which use traditional file paths. Platforms with package names (such as **Java**, **Cocoa**, and **Flutter**) require additional steps.
+
+</Note>
+
+First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`.
+
+![Highlighting where in the UI to find the file name in the stack trace](../code-mappings-stacktrace.png)
+
+If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename`.
+
+![Highlighting where in the UI to find the event JSON](../code-mappings-event-json.png)
+
+Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo).
+
+![An example of a file in source control](../code-mappings-source-file.png)
+
+Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code.
+
+For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible.
+
+![An example of a completed code mapping](../code-mappings-configure-modal.png)
 
 ## Troubleshooting
 

src/docs/product/integrations/source-code-mgmt/bitbucket/index.mdx

@@ -191,11 +191,33 @@ Stack trace linking takes you from a file in your Sentry stack trace to that sam
    - **Project** (required): This is the Sentry project.
    - **Repo** (required): This is the Bitbucket project associated with the Sentry project above. If you have more than one Bitbucket project being used per Sentry project, you'll need multiple code mappings.
    - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
-   - **Stack Trace Root** and **Source Code Root** (optional):
-     - If the file path in your Sentry stack trace frame matches the path to your source code, you don't need to set these values.
-       - For example, if everything after the branch (`main`) matches the file path of `code.py` using a source code path of `https://bitbucket.org/MeredithAnya/testing/blob/main/code.py`, you don't need to set either `stack trace root` or `source code root`
-     - If the file path in your Sentry stack trace frame doesn't match the path to your source code, you will need to replace the `stack_root` part of the file path with your `source_root` to make the file path match the source code path.
-       - For example, to get `src/code.py` to match `code.py` when the source code path is `https://bitbucket.org/MeredithAnya/testing/blob/main/code.py`, change the `stack trace root` to be set as `src/`, and leave `source code root` empty.
+   - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values.
+
+#### Stack Trace Root and Source Code Root
+
+<Note>
+
+The following information is only valid for platforms which use traditional file paths. Platforms with package names (such as **Java**, **Cocoa**, and **Flutter**) require additional steps.
+
+</Note>
+
+First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`.
+
+![Highlighting where in the UI to find the file name in the stack trace](../code-mappings-stacktrace.png)
+
+If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename`.
+
+![Highlighting where in the UI to find the event JSON](../code-mappings-event-json.png)
+
+Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo).
+
+![An example of a file in source control](../code-mappings-source-file.png)
+
+Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code.
+
+For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible.
+
+![An example of a completed code mapping](../code-mappings-configure-modal.png)
 
 ## Troubleshooting
 

src/docs/product/integrations/source-code-mgmt/github/index.mdx

@@ -257,17 +257,36 @@ Stack trace linking takes you from a file in your Sentry stack trace to that sam
 
 1. Fill out the form, then click **Save Changes**. Each form field is described below:
 
-   - **project** (required): This is the Sentry project.
-   - **repo** (required): This is the GitHub repository associated with the Sentry project above. If you have more than one GitHub repository being used per Sentry project, you'll need multiple code mappings.
-   - **branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
-   - **stack trace root** and **source code root** (optional):
+   - **Project** (required): This is the Sentry project.
+   - **Repo** (required): This is the GitHub repository associated with the Sentry project above. If you have more than one GitHub repository being used per Sentry project, you'll need multiple code mappings.
+   - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
+   - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values.
 
-     1. If the file path in your Sentry stack trace frame matches the path to your source code, you do not need to set these values.
+#### Stack Trace Root and Source Code Root
 
-        - ex. For example, everything after the branch (`main`) matches the file path of `code.py` using a source code path of `https://github.com/MeredithAnya/testing/blob/main/code.py` so you don't need to set a **stack trace root** and **source code root**.
+<Note>
+
+The following information is only valid for platforms which use traditional file paths. Platforms with package names (such as **Java**, **Cocoa**, and **Flutter**) require additional steps.
+
+</Note>
+
+First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`.
+
+![Highlighting where in the UI to find the file name in the stack trace](../code-mappings-stacktrace.png)
+
+If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename`.
+
+![Highlighting where in the UI to find the event JSON](../code-mappings-event-json.png)
+
+Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo).
+
+![An example of a file in source control](../code-mappings-source-file.png)
+
+Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code.
+
+For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible.
 
-     1. If the filename in your Sentry stack trace frame doesn't match the path to your source code, you will need to replace the **stack_root** part of the filename with your **source_root** to make the filename match the source code path.
-        - ex. For example, to get `src/code.py` to match `code.py` when the source code path is `https://github.com/MeredithAnya/testing/blob/main/code.py`, change the **stack trace root** to be set as `src/`, and leave **source code root** empty.
+![An example of a completed code mapping](../code-mappings-configure-modal.png)
 
 ### Code Owners
 

src/docs/product/integrations/source-code-mgmt/gitlab/index.mdx

@@ -132,18 +132,42 @@ Stack trace linking takes you from a file in your Sentry stack trace to that sam
 
 1. Fill out the form, then click **Save Changes**. Each form field is described below:
 
-   - **project** (required): This is the Sentry project.
-   - **repo** (required): This is the GitLab project associated with the Sentry project above. If you have more than one GitLab project being used per Sentry project, you'll need multiple code mappings.
-   - **branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
-   - **stack trace root** and **source code root** (optional):
-     - If the file path in your Sentry stack trace frame matches the path to your source code, you don't need to set these values.
-       - For example, if everything after the branch (`main`) matches the file path of `code.py` using a source code path of `https://gitlab.com/murdith-group/issa-project/-/blob/main/code.py`, you don't need to set either `stack trace root` or `source code root`
-     - If the file path in your Sentry stack trace frame doesn't match the path to your source code, you will need to replace the `stack_root` part of the file path with your `source_root` to make the file path match the source code path.
-       - For example, to get `src/code.py` to match `code.py` when the source code path is `https://gitlab.com/murdith-group/issa-project/-/blob/main/code.py`, change the `stack trace root` to be set as `src/`, and leave `source code root` empty.
+   - **Project** (required): This is the Sentry project.
+   - **Repo** (required): This is the GitLab project associated with the Sentry project above. If you have more than one GitLab project being used per Sentry project, you'll need multiple code mappings.
+   - **Branch** (required): This is the default branch of your code we fall back to if you do not have commit tracking set up.
+   - **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values.
+
+#### Stack Trace Root and Source Code Root
+
+<Note>
+
+The following information is only valid for platforms which use traditional file paths. Platforms with package names (such as **Java**, **Cocoa**, and **Flutter**) require additional steps.
+
+</Note>
+
+First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`.
+
+![Highlighting where in the UI to find the file name in the stack trace](../code-mappings-stacktrace.png)
+
+If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename`.
+
+![Highlighting where in the UI to find the event JSON](../code-mappings-event-json.png)
+
+Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo).
+
+![An example of a file in source control](../code-mappings-source-file.png)
+
+Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code.
+
+For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible.
+
+![An example of a completed code mapping](../code-mappings-configure-modal.png)
 
 ### Suspect Commits
 
-Once you've set up stack trace linking, Sentry can use information from your source code provider to suggest the commit that likely introduced the error. After pinpointing the suspect commit, you can also identify the developer who made the commit and assign them the task of fixing the error.
+Once you've set up stack trace linking, Sentry can use information from your source code provider to suggest the commit that likely introduced the error. The first frame in the stack trace is considered suspect when looking at them top-down. If the first frame is not in-app, the next frame is considered suspect.
+
+After pinpointing the suspect commit, you can also identify the developer who made the commit and assign them the task of fixing the error.
 
 ![Issue detail highlighting suspect commits](highlighting-suspect-commits.png)
 

src/docs/product/issues/suspect-commits/index.mdx

@@ -66,11 +66,35 @@ Sentry will automatically try to set up code mappings on Python and JavaScript p
 #### Code Mapping Form Fields
 
 - **Project** (required) - The Sentry project.
-- **Repo** (required) - The GitHub repository associated with the Sentry project above. If you have more than one GitHub repository being used per Sentry project, you'll need multiple code mappings.
+- **Repo** (required) - The GitHub or GitLab repository associated with the Sentry project above. If you have more than one repository being used per Sentry project, you'll need multiple code mappings.
 - **Branch** (required) - The default branch of your code we fall back to if you don't have commit tracking set up.
-- **Stack Trace Root** and **Source Code Root** (optional):
-  - If the file path in your Sentry stack trace frame matches the path to your source code, you don't need to set these values. For example, everything after the branch (`main`) matches the file path of `code.py` using a source code path of `https://github.com/MeredithAnya/testing/blob/main/code.py` so you don't need to set the **Stack Trace Root** and **Source Code Root**.
-  - If the filename in your Sentry stack trace frame doesn't match the path to your source code, you'll need to replace the **stack_root** part of the filename with your **source_root** to make the filename match the source code path. For example, to get `src/code.py` to match `code.py` when the source code path is `https://github.com/MeredithAnya/testing/blob/main/code.py`, change the **Stack Trace Root** to be set as `src/`, and leave **Source Code Root** empty.
+- **Stack Trace Root** and **Source Code Root** (optional): See below for information on determining these values.
+
+#### Stack Trace Root and Source Code Root
+
+<Note>
+
+The following information is only valid for platforms which use traditional file paths. Platforms with package names (such as **Java**, **Cocoa**, and **Flutter**) require additional steps.
+
+</Note>
+
+First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is `src/main.py`.
+
+![Highlighting where in the UI to find the file name in the stack trace](code-mappings-stacktrace.png)
+
+If you aren’t sure, you can look at the event JSON by clicking on the `{}` button in the event header. Find the text in the frame's `filename`.
+
+![Highlighting where in the UI to find the event JSON](code-mappings-event-json.png)
+
+Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is `flask/src/main.py` (`empower` is ignored since it is the name of the repo).
+
+![An example of a file in source control](code-mappings-source-file.png)
+
+Compare the file path from the stack trace with the path found in your source repository. In this example, the `src/` folder in the stack trace matches the `flask/src` folder in the source code. Using that information, set the **Stack Trace Root** to `src/` and the **Source Code Root** to `flask/src/`. This tells Sentry to replace all file paths beginning in `src/` with `flask/src/` when searching for the source code.
+
+For best results, we recommend always providing a non-empty value for the **Stack Trace Root** when possible.
+
+![An example of a completed code mapping](code-mappings-configure-modal.png)
 
 The first frame in the stack trace is considered suspect when looking at them top-down. If the first frame is not in-app, the next frame is considered suspect.