← Guides

Intro to Jira for Digital

Jira is very flexible… which means it’s easy to get lost. We hope this helps.

Agile for Digital

Not all teams use the same processes and Jira enables each. If you release every day or week, you are probably following a Kanban process. Monthly releases are a bit more Scrum. We have suggestions for both. We’ll get into those below, after going over a few concepts so we have common vocabulary. While Banno hasn’t subscribed to any particular agile methodology, individual teams are free to adopt an appropriate agile methodology and/or agile principles that suit them best.

Team Projects

Each team has a Jira Project, including the Product team. All external feature initiatives will have an Initiative issue in the Product Projects. Each team involved in a feature will have at least one corresponding child Epic in their team project which they can use to further break the work down into Stories and/or Tasks. For engineering projects that do not relate to a Product initiative each engineering team can structure their tickets/process/boards as they see fit.  Generally it is best practice to group related tickets that are not bugs under an Epic or Story.

Tickets, aka Issues

Every unit of work in Jira, such as a story or an epic, is uniformly referred to as an issue (or ticket). Each issue has a field called issue type, which represents the type and purpose of the issue. We have the following issue types:

  • Epic: This represents a group of work that is broken down into finer-grained requirements via stories and tasks that are attached to the epic. In Jira, epics are usually used to define the “theme” for several stories or tasks that will be part of it, as well as modules or major components in a big development project. You may have more than 1 Epic per Initiative in your team. Epics may also be used for a group of internal work not associated with an Initiative.
  • Story: This represents a single feature to be implemented. It is usually used to capture requirements from the end user’s perspective. For this reason, stories are sometimes written in nontechnical language and focusing on the desired results of the feature. Some teams may not use these and these should be viewed as optional.
  • Sub-Task: This represents a task that is part of a Story. Use these to break down a Story into separate efforts.
  • Task: This represents a generic task that is not a bug or a story, but which needs to be completed. These should be small enough to give a reasonable estimate of effort, and should represent a single goal. In addition we have issues for Bugs that may have no parent:
  • Bug: This represents a defect or problem that needs to be fixed in the product. We are also using Jira [[#Portfolio]] which adds additional, customizable levels of hierarchy. We have defined one level above Epics, the Product Initiatives. These represent cross-functional feature projects. You may not ever create one if you aren’t a Product Manager.

Initiatives, Epics and SubTasks

Our Product Managers create Initiatives for items on the Roadmap. As Initiatives begin discovery meetings, a member of each team involved will typically add an Epic for their team and put the Parent issue as the Product Initiative. As you add details and additional Story and/or Task Issues within your Epic, the estimates you make roll up and are visible to the rest of the team. Simply by you updating the estimate, we can figure out if we need more people or time to implement an Initiative. It also gives visibility into your current status - hopefully resulting in less interruptions and questions for you to answer. If you create additional Epics in support of an Initiative, remember to add the Parent Link to the Initiative. Note that Jira does not allow Epics to be parents of Epics. Also note that Stories are made up of Sub-Tasks. If you create a Task and later want to group it under a Story, you will need to convert the issue from Task to Sub-Task.

More on Agile

Scrum Projects

Scrum projects use sprints for organization of work for the team. Mobile teams, for example, have month-long sprints marked by releases at the end of the month. Some features may cross sprints in duration, and the tasks will be spread across more than 1 sprint. The team leads will add sprints as they come within 6 months of the current date. You can see all of a team’s current sprints and the work allocated to each in the project Backlog Board. It’s easy to move a task from one sprint to another in the Backlog Board. You can also examine just the active sprint.

Within a sprint, tickets are shown in swimlanes for each state - To Do,

In Progress and Done. This is a large topic and we suggest reading more. The book quoted in this document (Jira Software Essentials: Plan, track, and release great applications with Jira Software, 2nd Edition by Patrick Li) is good for Jira use as well as Scrum and Kanban. The website www.scrum.org is a great resource. More reading on Epics: https://www.atlassian.com/agile/tutorials/epics

Kanban Projects

Kanban is a fairly simple system used to plan, manage, and track work using cards and a board.  On the board each column represents the state or status of a card that is in that column.  Commonly used columns are Backlog, Selected for Development (sometimes this also appears as Planning), In Development, Needs Review, Done. A key component of Kanban is limiting the work in progress (WIP).  By limiting the work in-progress focus is created.  WIP limits lead to a reduction in bottlenecks and thus create a more consistent cadence for a team’s work.  Some examples:

  • In Development:  if your team works with a ratio of one engineer to one ticket then set the WIP upper limit for the In Development column to your team number.  If you use a two engineer to one ticket ratio (pairing) then set the upper limit of your WIP to half your team’s number of engineers.  The goal here is to keep your team from taking on more work than they should.
  • Reviews:  set this number fairly low, like two.  This is a forcing mechanism to keep your team reviewing tickets and removing bottlenecks.  A ticket from In Development can’t be moved into review if the upper limit has been reached and thus will force a review of existing work. As issues are moved across the board (left to right) it becomes fast and easy to visualize the work a team has in flight.

How does this relate to Github?

Github is a great tool for engineers and engineering teams to collaborate on work (code) but it is not a great tool for teams outside of engineering and it does not do a great job of tracking non-coding work an engineering team does (things that are not a PR eventually).

We do not want to change anything about how you use GitHub for engineering related work.  Jira is a tool built for planning and managing work.  Our goal is to transition away from using Github Issues to Jira Issues, and are trying to make that as easy as we can. We can import Github Issues, if that helps. Jira is integrated with Github so you can tie your commit messages and PRs to Jira tickets, if your team wants to do so. More on this below.

Using GitHub and Jira together

See Jira Cloud Documentation on Integrating with development tools for more information, but here are the highlights:

Relate a GitHub Pull Request to a Jira ticket

GitHub Pull Requests can show in related Jira tickets by putting the Jira ticket number in the PR title. It is case-sensitive. This is typically preferred as it’s hard to remember the Jira ticket number for every commit. Will show in Jira as:

You can embed a link in a comment on GitHub to a Jira ticket by including {project}-{ticket number} in a comment. For example: [WEB-94] shows additional information for this works. Will display as:

Show commits in Jira

Putting a Jira ticket number in a commit on a branch will result in the commit showing in the Commits section in Jira. Will show in Jira as:

Getting set up

This section will walk you through the initial experience and explain most of the buttons and views. Feedback welcome. If you don’t already have an invitation, you can fill out an Account Request form or email groundcontrol@banno.com or pop in #org-ground-control on Slack to kick off a request. When you first get your invitation email, click the link to sign up. Next up, click “Software Development” and then “Software Engineer”. Your first view will be a list of all of the team projects we have set up with some side menus for navigation. The lower left button with your initials on it is your Profile. Let’s personalize that first. Click “Profile”. Tap on “Manage Your Account”. Click on your  initials to add a photo of yourself. (No fair using your dog.)  Also set your location so the time zone is correct. You can adjust the rest as you like, or not. Make sure you click Save. When you are done, you can close all of the new windows to get back to the Projects tab. Jira opens a new browser tab each time you click on something that takes you somewhere new, so you never lose your browser tabs.

In the Projects view, click on your team’s project. Whether you use Scrum or Kanban, your team’s Project has a Board. Depending on which Agile methodology your team uses, you’ll be shown a Scrum board or a Kanban board. Scrum: Kanban: Each of these shows work currently marked for development. You can switch projects at any time if you are curious what other teams are doing using the drop down in the upper left. To look at an issue, click the Issue number: Scrum: Kanban: This will open a view with the Issue’s details. You can edit anything by clicking on it. To see all of the issues for a team, click on “Issues and Filters”. You’ll then see a list of choices for viewing Issues. Choose “Open Issues” to see all Issues that are, well, yeah, not Closed. Again, you can edit anything here by clicking on it. You can also get a view without the clutter by clicking on the Issue number: Which will get you this: NOTE: When you get the message at the top, click “See the old view”. The new views are harder to work with and you will hate it. Yes, people have complained to Atlassian about it. If you do this by accident, you can change it back in your Profile -> Personal settings. This will get you the more detailed view: This shows you all of the fields available for editing. You can change the status of an issue to `In Progress` or `Done` by clicking on the `Workflow` drop-down. This view also shows you any Github events relating to this issue, and lets you create branches, PRs, etc right from Jira, if you want. Jira is integrated with Github so you can tie your commit messages and PRs to Jira tickets. Simply put the ticket number (e.g. IOS-11) in the commit message to tie them together. You can collapse the menu if you want even more room.

How do I create an Issue?

There are a couple of ways to do this. We’ll show you a couple of the easiest. That big + in the leftmost menu is The Create Button. It’s always visible so you can do this from any view. You can select which project to put your new ticket in within the Create view. There are options to link your issue to a parent issue, like an Epic or Story. Scroll down a bit to get those: The 2nd easiest way to do this is to start from the parent Initiative, Epic or Story issue and create a Sub-task from there:

What about the rest of the items in the Menu?

Backlog (if visible - may not appear for all projects)

“Backlog” will give you a list of issues organized by Epics or Versions. You can click on Epics or Versions to expand that list as well.

Active Sprints (Scrum) or Kanban Board (Kanban)

This gets you the column view of Issues with “To Do”, “In Progress”, etc.

Reports

Stuff like Burndown Chart, Velocity Chart, etc. Interesting to poke around in. Will get more useful with time.

Releases

We may use this more in the future. Not terribly interesting right now.

Pages

We haven’t made use of these yet.

Components

Ditto, nothing much to see here

We’ve added a link straight into Github for several Projects. They look like this:

Team Repo View

Jira is integrated with Github so you can tie your commit messages and PRs to Jira tickets. Simply put the ticket number (e.g. IOS-11) in the commit message to tie them together. To help linking Github and Jira, we’ve added tools for each team as a view from Jira into the Github repo. They look like this: This will open a new browser window with a list of all commits. If you forget to add the link in the commit message, you can do so within Jira.

Git Commits

The “Git Commits” button on the menu has been added by an integrated tool for tying Github and Jira. This link will show you all commits tied to issues for the team. It can be rather slow and either quite noisy or empty as it’s trying to match the Issue number in commit messages and they pattern match to some older items. This should improve with time. Right now it’s a bit… useless, to be honest. We recommend that you ignore it for now.

What about that other sidebar?

More tools are found in here. You’ve used the lowest one to manage your Profile. The button at the top will give you another set of options and a new view: This is the System Dashboard. A Dashboard is a collection of tools to let you get insights into your team’s work, or across teams. You can create as many as you want. We’ve created a few to get you started. Feel free to copy them, add widgets and re-arrange however you want. You can keep them private to yourself only, share them with your team, or with everyone. To see all of the shared Dashboards, tap the upper right “…” button and select “Find Dashboard”. Note that you do not have to use Dashboards - some folks just work from the team board and that’s all.

Projects

This gets you back to the list of all current projects.

Issues and Filters

This view lets you do some more searching across all projects for issues, not specific to any one project. You can use the filters to narrow it down, or just use your project view instead of this one.

Portfolio

Portfolio brings all of the work for all of the teams together in a combined view. All Initiatives are shown, and one can drill down into each Initiative to see which teams have Epics associated with an Initiative, and then one can drill down further to view the Stories and Tasks included in the Epics.

What is the status of every team involved in an Initiative?

This is where the beauty of Jira Portfolio shines through. All Initiatives are shown, and one can drill down into each Initiative to see which teams have Epics associated with an Initiative, and then one can drill down further to view the Stories and Tasks included in the Epics. To see the list of all plans, click “View all plans”. Here you’ll see our Banno 6-Month Roadmap. By default, it will show you all Epics within Jira. Click on the filter to change to Initiatives: Initiatives in the list with an arrow in the left-most column have epics under them. Drill down by clicking on the arrow. If a team has added Stories or Sub-tasks to an Epic, there will be more levels you can drill down to see all of the work across each team involved in an Initiative. Estimates within the sub-tasks will roll up to the total for an Epic. We’re just tapping into the power of Portfolio. Currently, you can see the example plan or play with creating your own plans.

Git

The last button on the top part of the menu is a view into our integration between Github and Jira. Clicking it will give you a list of all of our repositories. Yeah, not terribly useful at this level. We have a lot of repositories.

Starred and Recent

This will give you a list of stuff you have recently accessed and anything you’ve marked as a favorite. To mark a view as a favorite, click the star in the upper right on the view.

Another way to search for issues and recent boards, projects, filters, etc.

Notifications

Not much here at the moment.

Switch to…

This gives you a list of all of our Atlassian products - Jira Software is what we are using, currently. The others are not relevant yet. It will also keep a list of your recent projects if you want to hop around using that menu item.

Help

Access to documentation, tutorials etc. Pretty obvious.

Miscellaneous

  • One should not delete an Issue - please close it. We’ve added a resolution of “Opened by mistake”.
  • If you are creating several Issues that are all similar, you can create the first then “Clone” it, and move it into the appropriate project. Way better than copy/pasting.

Give me more Jira!

Importing issues from Github to Jira

The easiest way to move issues from Github into Jira is to export the issues into a CSV file then import them in Jira. Here is one way to do this:

username = "JanenePappas"
password = "your-token-here"
  • Run the script in a terminal window like this: python ./github\_issues\_to\_csv.py Banno/\<repo-name\>
  • Use the resulting .csv file to import into Jira. You may need admin permissions to do this - if you don’t see this option, ask in our Slack channel #org-jira
  • Enjoy all of your new issues!