Like many Sketch plugins, Jira Cloud for Sketch indulges in some slightly risky behaviour in order to provide a more compelling user experience. This includes:
- Invoking Sketch's internal classes directly
- Invoking classes provided by some of Sketch's dependencies (i.e. AFNetworking)
- Modifying properties of NSView instances created by Sketch
- Adding new subviews to NSView instances created by Sketch
- Using deprecated Cocoa classes
Items 1 through 4 may potentially break after a Sketch upgrade, if the developers change or remove a class, dependency, or UI element that we depend on. Item 5 is less likely to cause issues, but may eventually break due to a macOS update that removes a deprecated class that we depend on.
We've made some effort to minimize the risk of failure, and to degrade gracefully (i.e. avoid crashing Sketch) in case of failure. However, depending on the nature of the underlying change, the failure mode may vary. This guide is designed to help an end user or support engineer remedy problems if they occur.
If the user has recently upgraded Sketch, the UI layout may have changed in such a way that the plugin can no longer find the correct NSView to add the 'Export to Jira' button to. As a workaround, it should still be possible to export images by using the 'Jira' item in the 'Plugin' menu, or by pressing ⌘+⌥+J. Please also raise an issue for the plugin maintainers to investigate.
This usually indicates that the plugin isn't actually installed. Please try downloading and re-installing the plugin. If symptoms persist, raise an issue for the plugin maintainers to investigate.
This may be a problem caused by a Sketch plugin. To determine which plugin is causing the issue, try removing them one-by-one from the Sketch plugin's directory at ~/Library/Application\ Support/com.bohemiancoding.sketch3/Plugins/ and reproducing the crash. If the offending plugin is Jira Cloud for Sketch, please raise an issue for the plugin maintainers to investigate.
If the broken plugin is critical to your workflow, you may downgrade Sketch by downloading and installing an earlier version.
This could indicate that one of the Objective-C classes depended on by the plugin has changed, or a bug in the plugin. Please raise an issue for the plugin maintainers to investigate. You can also try the other troubleshooting steps below.
The Sketch plugin tries hard to determine if a request to Jira Cloud failed due to a permissions issue and display an appropriate error. However, different Jira Cloud REST resources have different failure modes depending on the user's permissions, so there's a chance that the plugin will misinterpret a returned error code. Check with your Jira Cloud administrator that you have the appropriate permissions for the operation that is failing.
Plugin logs are written to ~/Library/Logs/com.bohemiancoding.sketch3/Plugin Output.log. This file is cleared by Sketch on startup, so be sure to reproduce the issue before capturing the logs.
The plugin's UI is provided by a Safari WebView. You can view errors logged to the Safari console by:
- Enabling the Safari Develop menu
- Right-clicking on the Jira panel and selecting 'Inspect Element'
- Clicking on
Console
Warnings and errors will be displayed in yellow and red, respectively. Note that there are a couple of known but bengign issues with a couple of the plugin's dependencies. Warnings about PropTypes and failures to load .js.map files are usually safe to ignore.
Plugin settings are stored in ~/Library/Preferences/plugin.sketch.jira-sketch-plugin.plist. You can view these settings with the following command:
/usr/bin/defaults read ~/Library/Preferences/plugin.sketch.jira-sketch-plugin
Or clear these settings with:
/usr/bin/defaults delete ~/Library/Preferences/plugin.sketch.jira-sketch-plugin
NOTE: the authToken stored in the plist is a temporary bearer token valid for a short period (~15 minutes, at time of writing) from creation. Do not share tokens that are still valid with others, or post them on the Internet, etc.
Various configuration settings (log levels, refresh intervals, etc.) can be modified by editing jira.sketchplugin/Contents/Resources/config.json.
To aid in diagnosis, you may wish to add additional logging to the plugin and create a development build. Check README.md for a guide to building the plugin.
Or, if you're feeling brave, you can modify the transpiled CocoaScript in jira.sketchplugin/Contents/Sketch/*.js or transpiled JavaScript in jira.sketchplugin/Contents/Resources/*.js. Note that you'll need to restart Sketch to pick up any changes.