Display and manipulate a breakdown structure of your JIRA Scrum project - even offline and only eventually connected to your JIRA system.
Alternatively, use your terminal to install the breakdown package.
apm install breakdown
To pull JIRA data into your Atom editor or push new issues and changes from Atom to JIRA, create a file with a
.bkdn filetype, e.g.
myjira.bkdn. The file must start with your configuration section and at least contain the following first five lines:
breakdown url: <JIRA URL> project: <key of JIRA project you want to create new issues in> query: <any JIRA JQL query to select your download dataset> ---
Whenever you change the
url or the
query of your
.bkdn file, your direct next step should be to pull the data from JIRA that is described by your configuration. Otherwise you might run into inconsistencies when changing contents in Atom and pushing back those changes to JIRA!
In the Packages menu, select Breakdown → Pull from JIRA to get your selected JIRA dataset into Atom. Whenever you pull the JIRA dataset into your Atom editor, all contents of the editor will be overwritten by the downloaded JIRA dataset.
Optionally, you can define in your configuration section to visualize the epic link key for stories and the parent issue key for sub-tasks.
In this explanation the CMD key stands for ⌘ on a Mac and CTRL on other platforms.
By default, after a pull all editor lines are folded. In the editor, folding can be controlled with the following keys
Saving the editor contents with CMD-S will beautify your text with correct spacing and indentation.
You can open an issue inside of JIRA by doing a CMD-MOUSECLICK on the issue key.
JIRA issues can be created and modified inside of the Atom editor. It´s always one issue per line. A new issue must contain at least the JIRA issuetype and the summary. The changes need to be pushed to JIRA to be effective.
In the following example a new epic is created, containing a new story which again contains a new sub-task:
Epic This will become a new epic Story This will become a new story inside of a new epic Sub This will become a new sub-task inside of a new story inside of a new epic
For any issue, the following JIRA fields can be modified: status, assignee, story points, fixversion, components and summary. For epics and stories even changing the issuetype is allowed. A full-fledged issue will be displayed like:
Story REST-32 As a developer, I want to have the story status highlighted (s:In Progress a:admin p:13 v:Version 3.0 c:Frontend)
An issue will start with the issuetype, which can be an epic, a story or a sub-task. It´s allowed to change epics into stories and stories into epics.
Issues which are already available in JIRA will have the JIRA issue key.
The next part of the issue is the summary, which is free text.
The summary is followed by a paranthesis section, containing:
s:<status>to indicate the issue status
a:<assignee>to indicate the JIRA user who is assigned to the issue
p:<story points>to indicate the story points for the issue, this is only valid for epics and stories and must be an integer number
v:<fixversion>to indicate the fixversion for the issue
c:<component>to indicate the component for the issue
Atom has a nice function to move entire lines up and down with CTRL-↑ and CTRL-↓, on Mac it´s CTRL-⌘-↑ and CTRL-⌘-↓.
Breakdown for Atom leverages this function, as it allows you to change your ranking in an quick and easy manner by still keeping a good overview of your entire breakdown structure.
If your query is not SORTED BY Rank ASC, you will mess up the ranking of your project when you apply the ranking inside of Atom and push the changes back to JIRA. For this reason ranking is a guarded feature in Breakdown for Atom - you have to activate it in your configuration section by adding the
rank entry to your
To change the rank for a story with sub-tasks, select the story line and all sub-tasks below, then apply the same command to move all selected lines at once.
Currently you cannot rank epics or sub-tasks, only the ranking of stories is supported.
Move stories from one epic to the other by using the cut and paste option of your Atom editor. Cut away a story from one epic and place it under the epic where you want it to be.
Issues can be removed by placing a deletion mark in front of the issue:
DEL Epic REST-26 ( s:In Progress p:13 ) This epic will be removed when pushed
In the Packages menu, select Breakdown → Push to JIRA to push your changes to JIRA. A push is always followed by an automatic pull to bring a current dataset back into your editor. If some issues could not be pushed, you will receive a warning notification with the reason code. In addition, those issues will disappear from the editor. Use the editor UNDO function to let those issues reappear.
For the creation of epics and stories from within Atom, you can optionally define in your configuration section a default fixversion and the default amount of story points to assign to those epics and stories when pushing them to JIRA. So you don´t need to specify those values for each new created issue in Atom. However, you can overwrite the setting in each issue. Configure with:
fixversion: <your default fixversion> points: <the default amount of points>
If you want to make sure to not accidently push back to JIRA, activate
nopush in your
options section, like:
In addition to the configuration section of the
.bkdn file, you can make some settings at the level of the breakdown package. Press CMD-, and navigate to the packages tab. Search for the breakdown package and click on Settings. You will find the following configuration options:
Good catch. Let us know what about this package looks wrong to you, and we'll investigate right away.