@atlassian/clientside-extensions-docs 2.2.0-rc-1 → 2.2.1-docs-1

package/content/server/framework/clientside-extensions/get-help.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: help
 subcategory: get-help
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Get help

package/content/server/framework/clientside-extensions/guides/extension-points/creating-an-extension-point.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: extension-points
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Creating an extension point

package/content/server/framework/clientside-extensions/guides/extension-points/extension-point-documentation.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: extension-points
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Extension point documentation

package/content/server/framework/clientside-extensions/guides/extension-points/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: extension-points
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Getting started

package/content/server/framework/clientside-extensions/guides/extension-points/providing-context.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: extension-points
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Providing context

package/content/server/framework/clientside-extensions/guides/extension-points/rendering-extensions.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: extension-points
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Rendering extensions

package/content/server/framework/clientside-extensions/guides/how-to/debugging-and-troubleshooting-an-extension.md

@@ -0,0 +1,169 @@
+---
+title: null
+platform: server
+product: clientside-extensions
+category: devguide
+subcategory: how-to
+date: '2021-05-24'
+---
+
+# Debugging and troubleshooting an extension
+
+Debugging an extension point can help you find out why your extension is not working as it should. This page describes how to debug a Client-Side Extension, including:
+
+-   How to identify if the extension was loaded on the page
+-   Why the extension didn't show up on the page
+
+This guide assumes you are an extension developer (plugin developer), and you [created an extension](/server/framework/clientside-extensions/guides/introduction/creating-an-extension/) that doesn't work for some unknown reason.
+
+This guide requires basic knowledge about the Atlassian plugin system and some experience with debugging HTML applications by using the browser DevTools. To troubleshoot an extension, you should know:
+
+-   How to turn on [browser DevTools](https://developer.chrome.com/docs/devtools/) and how to use the console panel.
+-   How to install browser extensions.
+-   How to use [`altas` CLI commands](/server/framework/atlassian-sdk/atlas-cli/).
+
+You should also know:
+
+-   Your Atlassian **plugin key**, that can be found in the `atlassian-plugin.xml` file.
+
+## How to check whether the extension loaded on the page
+
+Before you start troubleshooting the extension code, first, you should first ensure that the Atlassian plugin system loaded your plugin and that your extension was loaded on the page.
+
+### Check if your plugin was loaded
+
+1. First, you need to start the application, open the web browser, and navigate to the administration panel.
+2. Next, find and navigate to the **Manage Apps** page.
+3. On the list of all installed plugins, locate your plugin using **App key** (**plugin key**), and check whether all the plugin's modules are enabled:
+
+    ![Manage Apps](/server/framework/clientside-extensions/guides/how-to/debugging-and-troubleshooting-an-extension/plugin-troubleshooting.png)
+
+4. If your plugin is on the list and all the modules are enabled, you can proceed to the next step.
+
+{{% tip %}}
+
+If you haven't found the plugin on the list, you should try checking and inspecting the application log files. Depending on the application you are running the logs might be located in a different locations:
+
+-   [Logging and profiling Jira](https://confluence.atlassian.com/adminjiraserver/logging-and-profiling-938847671.html)
+-   [Working with Confluence Logs](https://confluence.atlassian.com/doc/working-with-confluence-logs-108364721.html)
+-   [Configure Bitbucket Server Logging](https://confluence.atlassian.com/bitbucketserverkb/configure-bitbucket-server-logging-779171678.html)
+
+{{% /tip %}}
+
+### Check if the extension was loaded
+
+Now that you know your plugin was loaded, you can check if the extension was loaded on the page.
+
+1.  Install the **[ASD Chrome extension](https://chrome.google.com/webstore/detail/atlassian-server-devtools/ifdlelpkchpppgmhmidenfmlhdafbnke)**. Open a web browser, turn on the DevTools and select the **ASD** tab.
+2.  Navigate to the page where you should see the extension point.
+3.  If the extension point is located in a different tab, e.g. Diff tab, select this tab on the page.
+4.  Now, in the DevTools window, select the **ASD** tab and choose the **WRM Inspector** option.
+5.  The **WRM inspector** allows you to see a list of all the web-resources loaded on the page. To filter the list and find a web-resource with your extension code:
+
+    -   Click on the **All context** option and select the name of the extension point
+    -   In the **Filter** field, type in part of your plugin name
+
+    ![Filtering and finding web-resource with ASD](/server/framework/clientside-extensions/guides/how-to/debugging-and-troubleshooting-an-extension/asd-finding-web-resource.png)
+
+6.  If you can find your web-resource on the list, it means that your extension was configured correctly, and it can be loaded on the page.
+
+{{% warning %}}
+
+If you can't find the **web-resource** with your extension, please check if the configuration of the webpack CSE plugin is correct. For more information refer to the guides:
+
+-   [Setting up the CSE webpack plugin](/server/framework/clientside-extensions/guides/how-to/setup-webpack-plugin)
+-   [Creating an Extension](/server/framework/clientside-extensions/guides/introduction/creating-an-extension)
+
+{{% /warning %}}
+
+## What to do when the extension did load but is not rendered on the page?
+
+CSE includes a debug mode that is disabled by default. You can enable the debug mode programmatically using the APIs from the `@atlassian/clientside-extensions-debug` package.
+
+To enable the runtime debug mode in your extension, follow these steps.
+
+1. Install the `@atlassian/clientside-extensions-debug` package:
+
+    ```
+    yarn add -D @atlassian/clientside-extensions-debug
+
+    # or
+
+    npm install --save-dev @atlassian/clientside-extensions-debug
+    ```
+
+2. Next, import the debug module in your code and use debug functions:
+
+    ```js
+    // my-extension.js
+    import { ModalExtension } from '@atlassian/clientside-extensions';
+    // 1. Add package
+    import { setDebugEnabled, setLoggingEnabled } from '@atlassian/clientside-extensions-debug';
+
+    /**
+     * @clientside-extension
+     * @extension-point bitbucket.ui.pullrequest.overview.summary
+     */
+    export default ModalExtension.factory((extensionAPI, context) => {
+        // 2. Turn on the debug mode and enable logging
+        setDebugEnabled(true);
+        setLoggingEnabled(true);
+
+        return {
+            label: 'Click to open a modal',
+            onAction: modalAPI => {
+                modalAPI.setTitle('Look, a Modal!');
+                modalAPI.onMount(container => {
+                    container.innerHTML = '<p>Hello World!</p>';
+                });
+            },
+        };
+    });
+    ```
+
+3. If you are using webpack with watch mode, you should see the page reload after saving the changes.
+   If not, use the [`atlas-package -DskipTests`](/server/framework/atlassian-sdk/atlas-package) command to rebuild your plugin and once it's done, manually refresh the page.
+4. Open the browser's developer tools and select the **Console** tab. In the same browser window, navigate to the page that should render your extension.
+5. If your extension is causing any problems you should see relevant information in the console tab, .e.g.
+
+    ![Example of validation error](/server/framework/clientside-extensions/guides/how-to/debugging-and-troubleshooting-an-extension/validation-error.png)
+
+6. Taking a look at the example image with the error:
+
+    ```
+    Schema validation issue with extension "<<extension name>>":
+    "Schema" failed to validate. Attribute "`iconBefore`" of type `IconType`! is missing in "Schema".
+
+    Meta information:
+
+    - location: `bitbucket.ui.pullrequest.overview.summary`
+    - extension: <<extension name>>
+    ```
+
+    The example validation error is showing information on what attributes are missing for the `bitbucket.ui.pullrequest.overview.summary` extension point. In this case, we need to provide the `iconBefore` attribute that is required.
+
+{{% tip %}}
+
+The above error is caused by missing required attributes.
+
+To catch mistakes like this sooner in development, you can turn on the [discovery mode](/server/framework/clientside-extensions/guides/introduction/discovering-extension-points/#revealing-extension-points-on-the-page) which will reveal location of extension points, and the list of required attributes for a given extension point.
+
+{{% /tip %}}
+
+{{% warning %}}
+
+Remember to include the `*-debug` package and turning the debug mode only in the **development** environment.
+
+The extension code shouldn't include the, e.g. `setDebugEnabled(true)` calls when you create a **production** version of the plugin.
+
+{{% /warning %}}
+
+## Further help
+
+If you followed the guide but are still not sure why the extension doesn't work, you can [report the issue in the Client-side Extensions project](https://ecosystem.atlassian.net/browse/CSE).
+
+Click on the create button and provide the reproduction steps. Please include as much information as you can, including:
+
+-   Application name and version
+-   A version of CSE modules you are using
+-   Browser vendor name and version

package/content/server/framework/clientside-extensions/guides/how-to/setup-page-bootstrapper.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: how-to
-date: '2021-04-30'
+date: '2021-05-19'
 ---
 
 # Setting up the CSE page bootstrapper
@@ -74,7 +74,7 @@ include the dependency when starting the project with AMPS.
 If you want to learn more about this practice, read
 [bundling extra dependencies in a OBR](https://developer.atlassian.com/server/framework/atlassian-sdk/bundling-extra-dependencies-in-an-obr/)
 
-In your `pom.xml` file, find your declaration of the Maven plugin for the product you're targeting (e.g: `bitbucket-maven-plugin`), and:
+In your `pom.xml` file, find your declaration of the Maven plugin for the product you're targeting (e.g.: `bitbucket-maven-plugin`), and:
 
 -   Import the `com.atlassian.plugin.clientsideextensions` package.
 -   Include the `atlassian-clientside-extensions-page-bootstrapper` as a plugin dependency.

package/content/server/framework/clientside-extensions/guides/how-to/setup-schema-loader.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: how-to
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Setting up the CSE schema-loader

package/content/server/framework/clientside-extensions/guides/how-to/setup-webpack-plugin.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: how-to
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Setting up the CSE webpack plugin

package/content/server/framework/clientside-extensions/guides/introduction/creating-a-modal.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Creating a modal

package/content/server/framework/clientside-extensions/guides/introduction/creating-a-page.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-19'
 ---
 
 # Creating a page
@@ -155,7 +155,7 @@ Rebuild your plugin with `atlas-package -DskipTests`, refresh your browser and n
 
 CSE provides a page extension factory to make it easier to create pages, especially when using TypeScript. This factory is a bit different than the others though.
 
-You may have noticed that the callback it receives doesn't return any attributes (like e.g: buttons or panels).
+You may have noticed that the callback it receives doesn't return any attributes (like e.g.: buttons or panels).
 That's because pages don't need an API to interact with products since they control the whole page.
 
 The callback only receives a container created by the CSE page bootstrapper where you can render your content, and

package/content/server/framework/clientside-extensions/guides/introduction/creating-an-extension.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-19'
 ---
 
 # Creating an Extension
@@ -78,6 +78,14 @@ Each factory receives a callback as an argument. This callback should always ret
 Attributes will be picked up by products and used to render your extension. In this case, you're specifying a label for your
 link and a URL where the user will be redirected when clicked. Bitbucket is using that information to render your link.
 
+{{% tip %}}
+
+Always remember to check the documentation of each product's extension point and supported attributes.
+
+You will read more information about [revealing extension points on the page](/server/framework/clientside-extensions/guides/introduction/discovering-extension-points/#revealing-extension-points-on-the-page) in the next part of the guide.
+
+{{% /tip %}}
+
 ## Comment annotations
 
 After defining your extension as a link with LinkExtension, you need to register it as part of your Atlassian Plugin.
@@ -107,6 +115,7 @@ import { LinkExtension } from '@atlassian/clientside-extensions';
 export default LinkExtension.factory(() => {
     return {
         label: 'Extensions are awesome!',
+        iconBefore: 'app-access',
         url: 'https://go.atlassian.com/clientside-extensions',
     };
 });
@@ -164,6 +173,7 @@ import { ButtonExtension } from '@atlassian/clientside-extensions';
 export default ButtonExtension.factory(() => {
     return {
         label: 'Extensions are awesome!',
+        iconBefore: 'app-access',
         onAction: () => {
             alert('They are awesome indeed!');
         },

package/content/server/framework/clientside-extensions/guides/introduction/custom-HTML-content.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Custom HTML content

package/content/server/framework/clientside-extensions/guides/introduction/discovering-extension-points.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-19'
 ---
 
 # Discovering extension points
@@ -25,7 +25,7 @@ Client-side Extensions (CSE) comes with some developer tools baked in to help yo
 
 To activate it, you need to go to a page that you know is using CSE and set the query parameter `?clientside-extensions` in the URL.
 
-1. Navigate to the PR you created for testing CSE (e.g: http://localhost:7990/bitbucket/projects/PROJECT_1/repos/rep_1/pull-requests/1/)
+1. Navigate to the PR you created for testing CSE (e.g.: http://localhost:7990/bitbucket/projects/PROJECT_1/repos/rep_1/pull-requests/1/)
 2. Add this query parameter to the URL: `?clientside-extensions`.
 
 You should see a glowing blue circle icon in the places where extension points are available.

package/content/server/framework/clientside-extensions/guides/introduction/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Getting started

package/content/server/framework/clientside-extensions/guides/introduction/using-extension-api.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: introduction
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Using the extensions API

package/content/server/framework/clientside-extensions/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: devguide
 subcategory: index
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # About Client-side Extensions

package/content/server/framework/clientside-extensions/reference/api/extension-api/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Extension API

package/content/server/framework/clientside-extensions/reference/api/extension-api/render-element-as-react.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Render element as React

package/content/server/framework/clientside-extensions/reference/api/extension-factories/async-panel.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # AsyncPanel

package/content/server/framework/clientside-extensions/reference/api/extension-factories/button.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Button

package/content/server/framework/clientside-extensions/reference/api/extension-factories/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Extension Factories

package/content/server/framework/clientside-extensions/reference/api/extension-factories/link.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Link

package/content/server/framework/clientside-extensions/reference/api/extension-factories/modal.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Modal

package/content/server/framework/clientside-extensions/reference/api/extension-factories/page.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Page

package/content/server/framework/clientside-extensions/reference/api/extension-factories/panel.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Panel

package/content/server/framework/clientside-extensions/reference/api/extension-points/hooks-and-components.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Hooks and Components

package/content/server/framework/clientside-extensions/reference/api/extension-points/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Extension Points

package/content/server/framework/clientside-extensions/reference/api/extension-points/schemas.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Schemas

package/content/server/framework/clientside-extensions/reference/api/extension-points-v1-deprecated.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: api
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Extension Points v1 (deprecated)

package/content/server/framework/clientside-extensions/reference/glossary/index.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: glossary
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Glossary

package/content/server/framework/clientside-extensions/reference/webpack-plugin/annotations.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: webpack
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Annotations

package/content/server/framework/clientside-extensions/reference/webpack-plugin/webpack-plugin.md

@@ -4,7 +4,7 @@ platform: server
 product: clientside-extensions
 category: reference
 subcategory: webpack
-date: '2021-04-30'
+date: '2021-05-11'
 ---
 
 # Webpack plugin

package/data/clientside-extensions.json

@@ -88,6 +88,10 @@
                             {
                                 "title": "Setup CSE schema-loader",
                                 "url": "/server/framework/clientside-extensions/guides/how-to/setup-schema-loader"
+                            },
+                            {
+                                "title": "Debugging and troubleshooting an extension",
+                                "url": "/server/framework/clientside-extensions/guides/how-to/debugging-and-troubleshooting-an-extension"
                             }
                         ]
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@atlassian/clientside-extensions-docs",
-    "version": "2.2.0-rc-1",
+    "version": "2.2.1-docs-1",
     "description": "Holds the official documentation for Altassian Server client-side extensions API.",
     "license": "BSD-3-Clause",
     "homepage": "https://bitbucket.org/atlassian/atlassian-clientside-extensions#readme",
@@ -73,12 +73,12 @@
         "set-last-updated": "doc-scripts set-last-updated",
         "version": "SKIP_VERSION_CHECK=true doc-scripts version",
         "link-check": "doc-scripts link-check",
-        "prepare": "SKIP_VERSION_CHECK=true doc-scripts validate",
+        "prepublishOnly": "SKIP_VERSION_CHECK=true doc-scripts validate",
         "prepack": "SKIP_VERSION_CHECK=true doc-scripts set-last-updated",
         "doc-scripts": "doc-scripts"
     },
     "optionalDependencies": {
-        "@atlassian/doc-scripts": "^2.6.0"
+        "@atlassian/doc-scripts": "^2.7.5"
     },
-    "gitHead": "13a12a28f26e93dfe228b324e97d8e4f59f56c2f"
+    "gitHead": "39444df70a849f8b04de5768cae26d3b5de94cec"
 }