Skip to end of metadata
Go to start of metadata

This page was initially created from the discussion at the bottom of the Using Jira to Manage Contributions page. Some major topics have (or will have) their own pages, e.g. Jira Contribution Notifications and Jira Contribution Searching.

If you have comments, feel free to continue the discussion at the bottom of the Using Jira to Manage Contributions page. Or comment on (or even contribute to) this page directly. Alternatively, feel free to create issues in the https://issues.broadband-forum.org/projects/TOOLS project.

Attachment comments

ARO contributions were made exclusively via the attached files, but CONTRIB allows "contributions" to be made directly via JIRA comments. This means that some contributions might not have any attachments at all. Is this to be encouraged?

There are not currently any guidelines on the use of JIRA comments versus contribution attachments, so please follow WA / PS / Project conventions.

Attachment names

As announced at the Q3 2018 Opening Plenary, there will soon be major enhancements to attachment naming. Watch this space..

Using Jira to Manage Contributions clearly states the attachment naming rules:

  • The filename must be of the following form (these naming rules are not currently enforced, but they soon will be)

    <number>-<one word company name>-[<author last name>-]<file subject/title>-<version>.<file extension>
  • In the above:
    • <number> is the contribution number, e.g. for CONTRIB-42 it's 42
    • <version> is a two-digit version, i.e. 000102...
    • Square brackets indicate an optional field, i.e. including the author last name in the filename is optional (but some WAs might require it)
  • For example, CONTRIB-13 might have an attachment called 13-BBF-Using JIRA to Manage Contributions-00.pptx or 13-BBF-Lupton-Using JIRA to Manage Contributions-00.pptx

However, these rules are not enforced, and are not in general being followed (sad).

There is general agreement that the best way to ensure that these naming rules are followed is to automate the inclusion of the mandatory fields. For example, given this file:

[<author last name>-]<file subject/title>.<file extension>

...<number>, <one word company name> and <version> can in theory be added automatically. Until this happens, please try to follow the rules!

An exception to the above is that, for contributions of type Draft (WTs, SDs etc.) it surely makes sense to continue to follow ARO naming conventions, e.g. WT-123a4_Rev.05.docx.

Attachment upload failure

Here are a couple of reasons why attachments might fail to upload.

  1. There's already an attachment with the same name: in this case you'll get a message like the one shown below (for some reason, the message isn't always displayed, so it might just seem like the upload is hanging, in which case you can cancel it); see Attachment Names (above).

    File "WT-106a8_Rev.07.docx" was not uploaded
    There is already an attachment with this name. Please include a version number in the file name and try again.
  2. Your JIRA session has timed out: in this case you'll see a message like the one shown below. Reload the page to ensure that you are logged in, then try again.

    File "CONTRIB 20371.01 Introduction text for SD-420 v2.docx" was not uploaded
    JIRA could not attach the file as there was a missing token. Please try attaching the file again.

Attachment ZIP files

ARO contributions did not permit named attachments, so when multiple files were associated with a contribution there was an incentive to use a ZIP file. This is certainly permitted for CONTRIB contributions, but will less often be necessary, because a CONTRIB contribution can have multiple attachments with different names.

There are not currently any guidelines on the use of ZIP files for contribution attachments, so please follow WA / PS / Project conventions.

Contribution names

The ARO contribution site was made read-only after the Q3 Helsinki meeting, and now all past ARO contributions have been added to the JIRA CONTRIB project, joining CONTRIB-20001, CONTRIB-20002 etc. that were created directly in JIRA.

We've assigned CONTRIB-nnnnn keys by order of creation date:

YearAROCONTRIB
1997dsl1997.001 through dsl1997.247CONTRIB-1 through CONTRIB-247
1998dsl1998.001 through dsl1998.258CONTRIB-248 through CONTRIB-505
...

2016bbf2016.001 through bbf2016.1288CONTRIB-16889 through CONTRIB-18176
2017 Q1-Q3bbf2017.001 through bbf2016.719CONTRIB-18177 through CONTRIB-18895
2017 Q3-Q4
CONTRIB-20001 and counting

All ARO contributions have an External issue ID field whose value is the ARO contribution name (omitting the revision number), e.g. "dsl1997.001". You can easily find an ARO contribution by typing the ARO contribution name in the Search field near the top right-hand corner of the JIRA window. This will find any JIRA issue that contains this string, so the results should always include the contribution that you're looking for, but might also include a few other issues. Of course, you can also search specifically for External issue ID values or patterns.

 Click here for example of searching for an ARO contribution...

Suppose you want to search for ARO contribution dsl2003.304.

Quick Search

Type dsl2003.304 into the Search box and hit Enter. That was easy!

Basic Search

Use the More menu to add the External issue ID field, then type dsl2003.304 and hit Enter. That was almost as easy!

Deleting attachments

Attachments can't be renamed, so to (effectively) rename an attachment it's necessary to download the file (if you haven't already done so), delete the attachment in Jira, and upload the renamed file.

An attachment is a contribution and contributions can't be un-contributed. Therefore, as was the case for ARO contributions, users can't delete their attachments. We recognise that this will often be just to rectify an error, but how, in the general case, can we distinguish "user uploaded file with wrong name and wants to fix it" from "user uploaded file and now wants to withdraw its content"?

If you have made a mistake and need to delete an attachment, please contact a CONTRIB administrator, which currently means one of April NowickiJohn BlackfordLincoln Lavoieand William Lupton.

Downloading contributions

See the Using Jira to Manage Contributions page's Download Contributions section for details of how to download single and multiple contributions.

Attachment names should by convention include a version number. But this is a convention and is not understood by JIRA, including the tools that are used for downloading attachments. Therefore, when you download a contribution you will currently get all versions of all attachments.

The current mechanisms for downloading contributions are off-the-shelf features and "they are what they are". We can collect requirements for how we'd like it to work, and then we can look into how to achieve this, which might well involve getting a third party to write some code.

To get an idea of what is possible try doing a search and downloading the results as XML or JSON. You will see that all the information is available, it's just a question of deciding how to present it and then (if necessary) writing some code to achieve this.

Finding field names

Fields are labeled using their field names, so it's usually easy to tell what they are called. There are just a few that aren't labeled, of which these are probably the most important:

  • key: the issue key, i.e. the full CONTRIB-nnnnn string
  • summary: the issue summary (title)

Joint contributions

There is no formal support for joint contributions, and a given contribution has only a single owner (reporter). Therefore, the contribution description needs to make it clear when a contribution is a joint one.

Linking to wiki pages

Contributions will sometimes need to reference wiki pages. For example, WT-408 is being developed in the wiki and will need to be referenced from CONTRIB contribution(s) that relate to it.

You should use the CONTRIB contribution More menu’s Link option to create a link to a wiki page (select Confluence Page on the left and then paste the page URL or search for it). The wiki page will now be listed in the Issue Links area, and if you go to the page you’ll see (at the top) a link back to the CONTRIB contribution.

You can also create a link from a wiki page to a CONTRIB item. Use the JIRA macro (type {JIRA}) to create a link to the CONTRIB contribution. If you now go to the CONTRIB contribution, the wiki page will be listed in its Issue Links area.

There’s nothing wrong with pasting a wiki page URL directly into a JIRA comment, but note that this doesn’t create a “formal" link between the CONTRIB contribution and the wiki page (the wiki page won’t know that it’s been linked to). Of course sometimes this is exactly what you want.

You can make a link in a JIRA comment more readable by using Ctrl-K (Cmd-K on a Mac) to insert it. This displays “[link title|http://example.com/]”, which you can then edit to put the displayed text (e.g. the wiki page name) before the vertical bar and the URL after the vertical bar.

Missing information, e.g. company name

Now that we have the "BBF Company" field, there's no reason to use the "Reporter Domain" field.

This field is available in all Jira projects, not just in CONTRIB. If you don't see it, this might be because you're using one of the OB (Open Broadband) projects... if this happens, please create a JIRA TOOLS issue or email tools@broadband-forum.org.

A new "BBF Company" field has been added. It's set on issue creation and can only subsequently be changed by an administrator. The field value will not change if the creator of the contribution moves to a new company.

This field has been set on existing issues created since January 2016. Its value is based on the current affiliation of the creator (reporter) and so may be wrong in a few cases. If you find any wrong values, please email tools@broadband-forum.org.

The field values are options selected from a list (like "BBF Project" etc.). This means that they're easy to change (let us know!). There are three special "company names": "Individual" (for individual members), "Distinguished Fellow" (for fellows) and "Unknown" (if the creator's username doesn't match a known BBF member company email domain).

Of course, you can use this field to search for contributions. It's better than the "Reporter Domain" field because it handles cases where a company has multiple email domains (and because, as already noted, it's only set on issue creation).

 Click here for details...

Here's how to find all CONTRIB issues created by BBF staff.

 Click here for details...

This is a case where the JQL (Jira Query Language) might actually be easier to understand than a picture!

project = CONTRIB AND "BBF Company" = "Broadband Forum" ORDER BY created DESC

Moving contributions

It may occasionally be necessary to move a contribution to a different JIRA project (most likely, to move a CONTRIB contribution to the LIAISE project).

This is a privileged operation and requires contacting a CONTRIB administrator, which currently means one of April NowickiJohn BlackfordLincoln Lavoie and William Lupton.

Notification emails

Notification emails are sent as each event occurs. If you prefer to receive a summary every day (say), you can create a Subscription (see below).

If you want to receive emails when contributions are created, you need to be a member of the contrib-watchers group. You will also be added as a watcher for all new contributions and can remove yourself from contributions in which you aren't interested. The Jira Contribution Notifications page explains how to join and leave the contrib-watchers group.

For existing contributions, you will receive an email when the contribution is modified by someone else if one or more of the following apply to you:

  • You are watching the contribution, which might be because you are in the contrib-watchers group, because you added yourself as a watcher, or because someone else added you as a watcher
  • The contribution is currently assigned to you, which means that you have an action to progress the contribution
  • You created (reported) the contribution in the first place

CONTRIB email subjects indicate the project and work area(s), which should make it easier to filter out emails of interest. For example:

BBF-JIRA {WT-114} [PHYtx] (CONTRIB-18088) Issues List for WT-114i3a3
FieldExplanation
BBF-JIRAThe subject always begins with this. Including BBF- allows you to easily distinguish BBF JIRA emails and your own company JIRA emails
{WT-114}The project's short name is enclosed in curly braces. If the project is Not Assigned, this is shown as {NA}
[PHYtx]The work area short name is enclosed in square brackets. If the work area is Not Assigned, this is shown as [NA], and if there are multiple work areas they are all shown, each with its own set of square brackets
(CONTRIB-18088)

The CONTRIB number is enclosed in round brackets

Issues List for WT-114i3a3
The contribution summary (title)


Also:

  • When a contribution is created, the email body includes additional BBF-specific information.

     Click here to see an example...

  • Additional info is also shown in LIAISE email subjects and bodies

     Click here to see an example...

    In the subject, the first field (in the curly braces) is the partner organization.

    BBF-JIRA {IEEE 1914} [R&T] (LIAISE-105) iLS from IEEE 1914 -- P1914.3 Radio over Ethernet (RoE)

Searching and filtering

A piece of advice. The "Updated" field changes whenever any issue attribute changes, even if a wiki page links to an issue. So you will always always want to use the "BBF Updated" field in filters and subscriptions! The "Updated" field will give you far too many false positives.

This is a huge topic. There is already some basic information in the Using Jira to Manage Contributions page's Search for contributions section. A JIRA Contribution Searching page will be created in due course, but in the meantime here is some random information.

Be aware that if you include a date (with no time-of-day) in a search, this means the beginning of the day. Therefore (for example) if you want to search for something that happened on 26-Feb-18 or 27-Feb-18, you need to use a starting date of 2018-02-26 (which means 2018-02-26T00:00:00) and an ending date of 2018-02-28 (which means 2018-02-28T00:00:00, i.e. just after 2018-02-27T23:59:59.999). The rule of thumb is "add a day to the ending date".

Any search can be saved as a filter. Filters have fixed URLs, have names, can be edited, and can be shared with others. Filter URLs can also be pasted into wiki pages and automatically become tables that contain the results of the search.

Filters also define how the results will be sorted, which columns that will be displayed in List view (or in Subscription emails), and in which order the columns will be displayed.

John Blackford has created some filters for BUS that could easily be adapted for use by other Work Areas:

 Click here for an explanation of these filters...

I'll use the JQL to explain these, but note that you can view or edit them in both Basic and Advanced modes. All of the JQL expressions are of the form Condition1 AND Condition2 AND ..., and therefore search for issues that meet all of the conditions.

BUS Current Quarter - New Contributions

project = CONTRIB AND status in ("In Progress", "Needs Work", "For Review") AND "BBF Work Area" = "Broadband User Services (BUS)" AND created >= 2017-09-08 AND created <= 2017-12-04 ORDER BY key ASC
ConditionExplanation
project = CONTRIBContributions...
status in ("In Progress", "Needs Work", "For Review")...that are in a state implying that they need to be reviewed in the meeting, and...
"BBF Work Area" = "Broadband User Services (BUS)"...that are BUS contributions (this also matches contributions that are in multiple Work Areas), and...
created >= 2017-09-08...were created after the end of the Q3 meeting, and...
created <= 2017-12-04...were created before the start of the Q4 meeting.
ORDER BY key ASCSort the results by key (CONTRIB-nnnnn), in ascending order


BUS Current Quarter - Late Contributions

project = CONTRIB AND "BBF Work Area" = "Broadband User Services (BUS)" AND created >= 2017-11-28 AND created <= 2017-12-04 ORDER BY key ASC
ConditionExplanation
project = CONTRIBContributions...
"BBF Work Area" = "Broadband User Services (BUS)"...that are BUS contributions (this also matches contributions that are in multiple Work Areas), and...
created >= 2017-11-28...were created after the Q4 contribution deadline...
created <= 2017-12-04...were created before the start of the Q4 meeting.
ORDER BY key ASCSort the results by key (CONTRIB-nnnnn), in ascending order


BUS Current Quarter - Updated Contributions

project = CONTRIB AND status in ("In Progress", "Needs Work", "For Review") AND "BBF Work Area" = "Broadband User Services (BUS)" AND created <= 2017-09-08 AND updated >= 2017-09-08 ORDER BY key ASC
ConditionExplanation
project = CONTRIBContributions...
status in ("In Progress", "Needs Work", "For Review")...that are in a state implying that they need to be reviewed in the meeting, and...
"BBF Work Area" = "Broadband User Services (BUS)"...that are BUS contributions (this also matches contributions that are in multiple Work Areas), and...
created <= 2017-09-08...were created before the end of the Q3 meeting, and...
updated >= 2017-09-08...were updated after the end of the Q3 meeting.
ORDER BY key ASCSort the results by key (CONTRIB-nnnnn), in ascending order

To modify existing filters for your own use:

  • Go to an existing filter URL, e.g. to one of the above BUS filters
  • In Basic or Advanced mode, modify the BBF Work Area criterion
  • Click Save As to save the modified filter under an appropriate and descriptive new name
  • If needed, adjust the sorting criteria and the displayed columns 
  • Click Details → Edit permissions to share the filter
  • Tell people!

You can't edit someone else's filter. You'll have to click Save as to save it as your own filter. Then you'll be able to change the JQL, change the column settings etc..

I'll pass on a tip that confused me for a while! Once you've loaded a filter, if you change the column settings, they take immediate effect. There's no need to save them (I couldn't work out why there was only a Save as button that insisted on my choosing a new name – that button changes to Save only if you change the filter or sort criteria, i.e. if you change the JQL).

Subscriptions (summary emails)

A piece of advice. The "Updated" field changes whenever any issue attribute changes, even if a wiki page links to an issue. So you will almost always want to use the "BBF Updated" field in filters and subscriptions! The "Updated" field will give you far too many false positives .

The time at which a subscription is executed is defined in the server time zone, i.e. in GMT!

If you prefer to get an email a day then, rather than signing up for notifications when CONTRIB issues are created or modified, you might like to look at subscriptions . These are a standard JIRA feature that work as follows:

  • You (or someone else) defines a search and saves it as a filter, e.g. it could be something like "PHYTx Updates" that lists all PHYtx contributions that have been created or updated in the last day
  • You create a subscription for this filter, asking for this search to be run at a certain interval and time (typically once a day) and for the results to be emailed to you

For example a subscription for the following filter will return all PHYtx contributions that have been created or updated in the last day.

project = Contributions AND updated >= -1d AND "BBF Work Area" = "Physical Layer Transmission (PHYtx)"

As with any filter, you can decide how the results should be sorted, and which columns should be displayed.

  • No labels