Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Made the location of the slides more obvious

Outline

Table of Contents
exclude(Outline|Child Pages)

Child Pages

See the Jira Contribution Webinars page for video recordings of related webinars.

See Using Jira to Manage Contributions - Member Webinar for the slides presented at the webinars.

Children Display

Introduction

Resources

Motivation and overview

  • Increasing use of the wiki, Jira and Bitbucket resulted in separate ARO and Atlassian worlds
    • BBF needed to consolidate on a single platform and, given the available features, this had to be Atlassian
  • Therefore BBF has switched from ARO to Atlassian (specifically to Jira) for managing contributions
    • Here, contributions really means traditional contributions, because many things that previously used ARO contributions are already using the wiki, Jira and Bitbucket (and this will continue)
    • Each contribution is what Jira refers to as an issue, in a new CONTRIB Jira project, and the contribution’s associated Word, PowerPoint, Excel (etc.) files are attached to this Jira issue

Expand
titleClick here for "JIRA 101"...
  • Jira supports projects (each project has a name and a short key) and projects contain issues (each issue has a number)
    • Therefore a Jira issue can be referenced as key-nnn, where key is the project key and nnn is the issue number
  • Each BBF contribution is an issue within a Contributions Jira project; the project key is CONTRIB so, for example, contribution 42 can be referenced as CONTRIB-42
    • This is analogous to bbf2017.042 (both the year and the number-within-year are encoded in the 42)
  • The CONTRIB project supports BBF-specific issue types, workflows and fields for selecting the Project, Project Stream(s) and Work Area(s)
    • Otherwise it looks like any other Jira project
  • Standard Jira mechanisms are used for creating and managing contributions
    • For example, searching and downloading attachments

What are the benefits?

  • Integrated platform (Confluence, Jira, Bitbucket) for all contributions

    • Confluence works with Jira and Bitbucket to provide a home for Work Areas and Projects, integrating project proposals, call agendas and minutes, and other project information

    • For software projects, Jira works directly with Bitbucket (and other tools such as Bamboo)

  • Sophisticated search capabilities

    • Simple, basic and advanced searches, supported by underlying Jira Query Language (JQL)

    • Wiki pages can embed Jira queries summarizing the status of a project’s contributions

  • Contribution life cycle management

    • Standard Jira features can be leveraged, including contribution status (workflow), comments, assignee, and priority

Quick reference

Note

Each use case links to more detailed discussion and examples below.


Use caseDescription
Go to Jira

Go to the wiki (or Bitbucket) and select BBF Jira from the  Application Navigator menu at the left-hand end of the menu-bar.

Search for contributions
  • Enter a search string into the box near the right-hand end of the menu-bar. For example:
    • If you know the contribution name, just type it, e.g. contrib-42 (you can usually just type the number, e.g. 42)
    • If you want all unresolved contributions, type contrib unresolved
    • If you want contributions containing the word 'cat', type contrib cat
Modify search criteria
  • Search results are displayed as a table; the search criteria are shown above the table
    • If you are in Advanced mode (which is unlikely unless you're an advanced user!), click Basic to select Basic mode
  • If desired, use the option menus to modify the search criteria
    • For example, modify to select
    • Or modify to select
  • If you want to use criteria that aren't currently displayed, click and select or search for them (recently-used ones are listed at the top)
    • For example, type bbf to select fields whose names include BBF and then select BBF Project; this adds a BBF Project option menu and you can now select or search for the desired project
  • Tip: To CONTRIB or any issue in alphanumeric order you need to know the magic word "key" like this:
Include search results in a wiki page
  • To include Jira search results in a wiki page, paste the search URL into the page
Expand
titleFor example, search for "contrib yang"...

This gives the following URL

Code Block
https://issues.broadband-forum.org/issues/?jql=project%20%3D%20CONTRIB%20AND%20text%20~%20yang

Pasting this URL into the page automatically generates a table listing all contributions containing the text "yang"

Jira
serverBroadband Forum Issue Tracker
jqlQueryproject = CONTRIB AND text ~ yang
serverIdd92875e6-bce1-3b6b-a909-e9268944d601


Download a specific contribution
  • You've either selected a single contribution (e.g. you searched for contrib-42) or else you've searched for contributions that meet your criteria
    • In the latter case you'll see a table; if you're in the List View, i.e. you don't see details of a single contribution on the right, type "t" or use (to the right of the search criteria) to select Detail View, or else click on the contribution that you are interested in
  • You (currently) need to download metadata (title, description, comments etc.) and attachments separately
    • To download metadata, select an option from the contribution's menu (you probably want Word or Printable)
    • To download a single attachment, click on the attachment
    • To download all attachments, click on the Attachments option menu and select Download All to download a ZIP file
Download contributions matching search criteria
  • You've searched for the (possibly) multiple contributions that meet your criteria
    • You'll see a table, and above the search criteria you'll see
    • Don't confuse this Export menu with the per-contribution Export menu (which is inside the contribution frame)!
  • You (currently) need to download metadata (title, description, comments etc.) and attachments separately; both of these are done via the menu
    • To download metadata, select the appropriate option from the menu (you probably want Full Content or Word)
    • To download attachments, select Attachments, select Folder name configuration = Issue key + Summary(recommended), and click Download all attachments; this downloads a ZIP file with a sub-directory for each contribution

Warning

When you click the Download all attachments button, Jira creates and downloads a ZIP file. However, this can take some time (especially if you are downloading lots of contributions) and there is no indication that this is what's happening. So please resist the temptation to click it twice!


Create a contribution
  • Go to the wiki (or Jira or Bitbucket) and select BBF Contribution from the Application Navigator menu at the left-hand end of the menu-bar
  • Select the Contributions (CONTRIB) Project and the Issue Type, then click Next
  • Fill in the required information (there's some quick guidance below each field) and then click Create
Edit a contribution
  • Fields that show a pencil icon as you move the mouse pointer over them can be edited in place
    • Click on the field value, type or select the new value, then confirm by clicking the tick or cancel by clicking the cross (or click Save or Cancel for multi-line text fields)
  • To add a new comment, click one of the buttons at the top-left or bottom of the window; this allows you enter and Add or Cancel the new comment
  • Alternatively, click the button at the top-left of the window; this pops up a new window in which you can edit multiple field values and optionally add a new comment
  • To add an attachment, click the button to bring up a new screen, and follow the instructions
Change the state of a contribution
  • New contributions are created in the FOR REVIEW state, and will return to this state whenever they need to be reviewed by the working group
  • If the contributor needs to do further work, the button forces the contribution to be assigned to someone (it should be the contributor) and changes the state to NEEDS WORK
  • If the editor needs to incorporate the contribution into a BBF draft, the button forces the contribution to be assigned to someone (it should be the editor) and changes the state to IN PROGRESS
  • If the contribution is once again ready for review, the button reverts the state to FOR REVIEW
  • If all work is complete, the button marks the contribution as Done and changes the state to COMPLETED
  • If the contribution is withdrawn, the button changes the state to WITHDRAWN
  • The button re-opens COMPLETED or WITHDRAWN contributions and changes the state to FOR REVIEW

Quick Summary Chart

Anchor
search
search
Search for Contributions

Jira has powerful search capabilities but is not especially intuitive. To do a basic search, follow these steps:

  1. Log in to Jira (same login as the Wiki): https://issues.broadband-forum.org/secure/Dashboard.jspa
  2. Click the “Projects” drop-down menu at the top left.
  3. Click “View All Projects”.
  4. In the list of All Project Types – All Categories, find the “Contributions” project and click on it.
  5. This will bring you to a random list of all the “Issues” in the Contributions project.
  6. Click on the “View all issues and filters” link in the top right corner (it’s a small blue text link below your profile icon). This will bring up new filter options.
  7. Click on the “More” filter drop-down menu, and select “BBF Project”. This will bring another new filter option for “BBF Project”.
  8. Click on the “BBF Project” filter drop-down menu and type “WT-NNN”. 

That's it! The other default filters and the filters in the "More" drop-down menu and provide many other options to adjust searching as needed.

Here are other options:

  • Quick search: enter a simple search string into the box near the right-hand end of the menu-bar, then hit Enter
  • Basic search: define or refine search criteria directly in the GUI
  • Advanced search: use Jira Query Language (JQL) to define sophisticated search criteria

Having performed a search, the resulting search URL can be pasted into a wiki page, at which point it's automatically converted to use the Jira macro and will render as a table containing the up-to-date search results. See the wiki section for examples and more details.

Anchor
navigation
navigation
A note on navigation

To get to Jira from the Wiki or Bitbucket, select BBF Jira from the  Application Navigator menu at the top left side of the menu bar.

There are two main ways of viewing contributions:

  • Using the Projects menu to view the Contributions (CONTRIB) project using various predefined filters
  • Using the Issues menu to (a) define, refine and view search results, and (b) view individual contributions

This is potentially confusing, because both approaches can generate similar views. For example the following both look similar but are generated in different ways.

Expand
titleClick here to see "Project" view showing all open issues...

https://issues.broadband-forum.org/projects/CONTRIB/issues/CONTRIB-10?filter=allopenissues


Expand
titleClick here to see "Issues" view showing the same open issues...

https://issues.broadband-forum.org/browse/CONTRIB-10?jql=project%20%3D%20CONTRIB%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC


Expand
titleClick here to see possibly more than you wanted about how this all works...

It helps me to realize that there are three different base URLs at work here, but what you actually see is strongly influenced by what you last did, i.e. by the "current project", the "current search", the "current mode" etc.

URLDescription
https://issues.broadband-forum.org/projects/CONTRIB

Selecting CONTRIB from the Projects menu goes to https://issues.broadband-forum.org/projects/CONTRIB, which immediately redirects to show the project aspect that you were most recently looking at. Hopefully this will be the issues, but it could be the summary or some other aspect.

If you don't see the issues, select them by clicking in the side-bar. Either way, you will be taken to https://issues.broadband-forum.org/projects/CONTRIB/issues.

But we're not done yet... you will now be automatically redirected to the default Open issues filter, which shows all open (unresolved) contributions ordered from the highest to lowest priority. So now you're at https://issues.broadband-forum.org/projects/CONTRIB/issues?filter=allopenissues.

But we're still not done... Jira now inserts the name of the first displayed contribution (i.e. the highest priority contribution) into the URL. So the displayed URL is something like https://issues.broadband-forum.org/projects/CONTRIB/issues/CONTRIB-10?filter=allopenissues.

You can now use the Switch filter menu to select a different predefined filter. All of these filters are in the context of the CONTRIB project. For example, selecting the Updated recently filter might take you to https://issues.broadband-forum.org/projects/CONTRIB/issues/CONTRIB-12?filter=updatedrecently.

Selecting View all issues and filters from this window simply goes to https://issues.broadband-forum.org/issues, i.e. it's the same as selecting Current search from the Issues menu (see below).

https://issues.broadband-forum.org/browse/CONTRIB

https://issues.broadband-forum.org/browse/CONTRIB-10

Actually, to tell the truth, selecting CONTRIB from the Projects menu goes to https://issues.broadband-forum.org/browse/CONTRIB, but it immediately redirects to https://issues.broadband-forum.org/projects/CONTRIB.

And selecting an individual contribution, e.g. CONTRIB-10, from the Issues menu goes to https://issues.broadband-forum.org/browse/CONTRIB-10.

https://issues.broadband-forum.org/issues

Selecting Current search from the Issues menu goes to https://issues.broadband-forum.org/issues, which immediately redirects to https://issues.broadband-forum.org/browse?jql=QUERY (where QUERY is the current JQL – Jira Query Language – query).

But we're not done... as before, Jira now inserts the name of the first displayed contribution. So the displayed URL is something like https://issues.broadband-forum.org/browse/CONTRIB-12?jql=QUERY.

The window now shows the search criteria in the current mode (Basic or Advanced). You can adjust it as usual.

Selecting Search for issues from the Issues menu is similar to selecting Current search, but it sets QUERY to an empty string.



Just remember these quick ways of going to a search window:

Multiexcerpt
MultiExcerptNamehow-to-get-to-search-window
  • Perform a quick search
  • Select Current search from the Issues menu
  • Click View all issues and filters when viewing a project

Quick search

Enter a simple search string into the  box near the right-hand end of the menu-bar, then hit Enter. See the examples below.

Text (case is ignored)Meaning
contrib catContributions whose containing the text 'cat' (text means summary, description or comments)

contrib

The Contributions project
contrib-123 Contribution 123 (you need the hyphen; 'contrib 123' searches for the text '123')
123Contribution 123 (you can omit the project if you are already looking at a contribution)
contrib unresolvedUnresolved contributions
unresolved contribUnresolved contributions (order doesn't matter)
my unresolved contributionsUnresolved contributions that are assigned to me (can also use 'contributions' because that's the project name; 'contrib' is the project key)
catAll issues (in any project) that contain the text 'cat'

Anchor
search-modify
search-modify
Basic search

Go to a search window. For example, do one of the following (in this case, I did a quick search for contrib unresolved):

Multiexcerpt include
MultiExcerptNamehow-to-get-to-search-window
PageWithExcerptUsing Jira to Manage Contributions

The top part of the search window will look like this if it's already in Basic mode

...or will look like this if it's in Advanced mode, in which case you need to click Basic to enter Basic mode.

In Basic mode, you can use the option menus to modify the search criteria (if you don't select any specific values for a field, all values are selected).

Five fields are always visible for selection:

FieldDescription
ProjectPresumably only CONTRIB is selected; don't change this unless you know what you are doing
TypeContribution type, e.g. choose Straw Ballot Comment to select only SB comments
StatusContribution status (workflow state), e.g. choose FOR REVIEW to select contributions that need to be reviewed by the working group (this is like Presentation Requested)
AssigneeCurrent assignee, typically the contributor when the state is NEEDS WORK or the editor when the state is IN PROGRESS
TextText in the contribution's summary, description or any of its comments

Use the More menu to make other fields available for selection (such fields are displayed only when they've been selected, e.g. the Resolution field is displayed for this example). In the case shown below, you can see that recently used criteria are shown first, and I've searched for fields whose names contain bbf.

If I select BBF Project I will now see this:

...and can select the project(s), by scrolling through the list and/or by searching for text within the project name. Here I've searched for yang (it's not case-sensitive) and have selected WT-355 and WT-383:

Advanced search

Go to a search window. For example, do one of the following (in this case, I did a quick search for contrib unresolved):

Multiexcerpt include
MultiExcerptNamehow-to-get-to-search-window
PageWithExcerptUsing Jira to Manage Contributions

The top part of the search window will look like this if it's already in Advanced mode

...or will look like this if it's in Basic mode, in which case you need to click Advanced to enter Advanced mode.

In Advanced mode, you can manipulate the Jira Query Language (JQL) directly. As you can see, it can be quite simple (and the complex-looking URLs are made much scarier by all the %20 etc. escapes) and as long as your query doesn't get too complex, you can flick back and forth between Advanced and Basic modes (this is a good way to learn some simple JQL).

For example, the final Basic search example, when switched to Advanced mode, is as follows:

There is surprisingly good context-sensitive assistance while editing JQL in Advanced mode, but I'll leave you to discover that for yourselves.

Anchor
wiki
wiki
Reference contributions and search results in wiki pages

Having performed a search, the resulting search URL can be pasted into a wiki page, at which point it's automatically converted to use the Jira macro and will render as a table containing the up-to-date search results.

For example, suppose you do a quick search for contrib yang. This gives the following URL:

Code Block
https://issues.broadband-forum.org/issues/?jql=project%20%3D%20CONTRIB%20AND%20text%20~%20yang

...and pasting this URL into the page automatically generates a table listing all contributions containing the text "yang":

Jira
serverBroadband Forum Issue Tracker
jqlQueryproject = CONTRIB AND text ~ yang
serverIdd92875e6-bce1-3b6b-a909-e9268944d601

Anchor
download
download
Download contributions

There are two cases to consider:

  • Specific contribution: you are viewing a specific single contribution
  • Contributions matching search criteria: you have performed a search that's matched zero, one or more contributions

Anchor
download-specific
download-specific
Download specific contribution

 There are two ways to view a specific contribution:

  • View it directly via a browse URL: the easiest way to do this is to do a quick search for the contribution number, e.g. a quick search for contrib-10 will take you directly to https://issues.broadband-forum.org/browse/CONTRIB-10
  • Select it from search results: search results are displayed in Detail View (list of results on the left and current contribution on the right) or in List View (list of results with no visible current contribution); if you're in the List View, i.e. you don't see details of a single contribution on the right, type "t" or use (to the right of the search criteria) to select Detail View, or else click on the contribution that you are interested in

You (currently) need to download metadata (title, description, comments etc.) and attachments separately.

  • To download metadata, select an option from the contribution's menu (you probably want Word or Printable)
  • To download a single attachment, click on the attachment
  • To download all attachments, click on the Attachments option menu and select Download All to download a ZIP file

Anchor
download-search
download-search
Download search results

You've searched for the (possibly) multiple contributions that meet your criteria.

  • You'll see a table, and above the search criteria you'll see
  • Don't confuse this Export menu with the per-contribution Export menu (which is inside the contribution frame)!

You (currently) need to download metadata (title, description, comments etc.) and attachments separately; both of these are done via the menu.

  • To download metadata, select the appropriate option from the menu (you probably want Full Content or Word)
  • To download attachments, select Attachments, select Folder name configuration = Issue key + Summary (recommended), and click Download all attachments; this downloads a ZIP file with a sub-directory for each contribution

Warning

When you click the Download all attachments button, Jira creates and downloads a ZIP file. However, this can take some time (especially if you are downloading lots of contributions) and there is no indication that this is what's happening. So please resist the temptation to click it twice!


Anchor
create
create
Create a contribution

  • Go to the wiki (or Jira or Bitbucket) and select BBF Contribution from the  Application Navigator menu at the left-hand end of the menu-bar
  • Select the Contributions (CONTRIB) Project and the Issue Type, then click Next
  • Fill in the required information (there's some quick guidance below each field) and then click Create
FieldNotes

This is the Jira project, so it's always Contributions (CONTRIB), not the BBF project.

These are the currently-supported contribution types.

Contribution TypeDescription
General Contribution

A general contribution

Note: this is the default

DraftA contribution that tracks the development of a BBF Project or Document
Straw Ballot CommentA comment on a Project or Document that is currently in Straw Ballot review
OtherA contribution that doesn't fit into any of the other categories


This is the contribution title (or summary).

The string None is initially displayed, and indicates that you haven't yet made a choice. If the contribution hasn't yet been assigned to a project, select Not Assigned.


Note

This field should be set automatically. You can adjust it if necessary.

If the contribution hasn't yet been assigned to a Project Stream, select Not Assigned.


Note

This field should be set automatically. You can adjust it if necessary.


Labels are optional. If you use them, please try to

  • Re-use existing ones where possible
  • Follow the project's naming conventions (if any)

You can change this later


Anchor
edit
edit
Edit a contribution

Fields that show a pencil icon as you move the mouse pointer over them can be edited in place.

  • Click on the field value, type or select the new value, then confirm by clicking the tick or cancel by clicking the cross (or click Save or Cancel for multi-line text fields)

To add a new comment, click one of the buttons at the top-left or bottom of the window; this allows you enter and Add or Cancel the new comment.

Alternatively, click the button at the top-left of the window; this pops up a new window in which you can edit multiple field values and optionally add a new comment.

To add an attachment, click the button to bring up a new screen, and follow the instructions

Anchor
workflow
workflow
Contribution workflow and state

Contributions use the workflow (state transition diagram) shown below.

  • The boxes are the states (the name of the current state is shown when viewing a contribution)
  • The lines (with arrows) are the transitions (the transition label is used for the button that initiates the transition)

In summary (nearly all of this can be inferred from the diagram):

  • New contributions are created in the FOR REVIEW state, and will return to this state whenever they need to be reviewed by the working group
  • If the contributor needs to do further work, the button forces the contribution to be assigned to someone (it should be the contributor) and changes the state to NEEDS WORK
  • If the editor needs to incorporate the contribution into a BBF draft, the button forces the contribution to be assigned to someone (it should be the editor) and changes the state to IN PROGRESS
  • If the contribution is once again ready for review, the button reverts the state to FOR REVIEW
  • If files are to be attached, the  button can be used in the FOR REVIEW, NEEDS WORK and IN PROGRESS states
  • If all work is complete, the button marks the contribution as Done and changes the state to COMPLETED
  • If the contribution is withdrawn, the button changes the state to WITHDRAWN
  • The button re-opens COMPLETED or WITHDRAWN contributions and changes the state to FOR REVIEW

The distinction between State and Resolution can cause confusion.

  • State is the current workflow state name (the possible states are a function of the workflow; the CONTRIB states are BBF-specific)
  • Resolution indicates whether and how the contribution has been resolved (the possible resolutions are fixed: UnresolvedDoneWon't DoDuplicate and Cannot Reproduce)
    • Completing or withdrawing a contribution automatically set Resolution to Done or Won't Do (respectively)
    • Jira uses the terms Open and Closed for Resolution = Unresolved and Resolution != Unresolved (respectively)