Skip to end of metadata
Go to start of metadata

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

 Click 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

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
 For example, search for "contrib yang"...

This gives the following URL

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"

T Key Summary Assignee Reporter P Status Resolution Created Updated Due
Loading...
Refresh

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

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

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.

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.

 Click here to see "Project" view showing all open issues...
 Click 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:

  • 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'

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):

  • Perform a quick search
  • Select Current search from the Issues menu
  • Click View all issues and filters when viewing a project

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):

  • Perform a quick search
  • Select Current search from the Issues menu
  • Click View all issues and filters when viewing a project

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.

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:

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":

T Key Summary Assignee Reporter P Status Resolution Created Updated Due
Loading...
Refresh

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

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

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

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
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.

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.

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


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

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)
  • No labels

145 Comments

  1. I think people need to be able to choose which workgroups/projects they get contribution alerts for.

    also not every update of the contribution needs to generate an alert imo.

    1. I've changed CONTRIB to use the default notification scheme, so the following people will receive notifications for everything. Anyone can add themselves as a watcher to any JIRA issue.

      • All Watchers
      • Current Assignee
      • Reporter

      I will be adjusting this so everyone is informed of contribution creation. It will then be up to you to add yourself as a watcher for contributions that you want to track.

      If you would like to automatically receive all notifications for all contributions, please let me know. I'll add Michael Fargano anyway.

      Please post ideas for how you would like notifications to work in an ideal world, and I'll see what I can do.

      1. William,

        How do you know you want to 'watch' a certain contribution ? Is a single notification still send out to the email exploder when it is created?  Is there a way to change the From: email address, to make this WA/PS specific ?


        1. We can change the 'from' email address, but only for the entire CONTRIB project. The basic idea is to simulate the contrib@broadband-forum.org mailing list (which doesn't distinguish by WA/PS). We could look into whether the 'from' address or the subject could include some WA/PS/Project metadata that could assist mail filters.

      2. I've made the above change, so everyone with access to the project should now be notified only on contribution creation (unless you are a watcher, current assignee or reporter).

  2. Can JIRA default to initially assigning a contribution to the creator?

    1. Yes, I believe it can.

      1. The initial state is FOR REVIEW so there's no action on the creator, so why assign to the creator?

  3. I think assigning it to the creator helps searches, etc. Its also a logical starting point

    1. You can search on the creator if you want.

      The workflow definition is such that the assignee is the person who currently has an action, i.e. the ball is currently in the assignee's court. Making the initial assignee be the creator doesn't fit that. You could make a case for initially assigning it to the PSL (but, ahem, that's not possible out of the box).

      Other opinions?

  4. Different topic: Instead of "CONTRIB-##" I suggest "BBF-##"

    Reason: CONTRIB means nothing, where BBF can be important for external reference

    1. The team went through this discussion over the coarse of many months and came to a consensus of using CONTRIB (BBF was one of the other options).

  5. It looks like I'm getting an email every time a new contribution is created. How can I turn that off?


    1. Please can someone tell me how to turn off JIRA contribution notifications.
      1. So it's not just me .... (smile)

  6. We need a way for each user turn it off or on by user.

    I track these and want to get the notices.

    1. I agree! I'm the opposite, I don't want to get the notices.

      1. Sorry, this was a mistake! The current settings (during this evaluation period) do notify everyone who can see the CONTRIB project (which is SC, TC leaders and editors), but I should have disabled it before running my script to import the OD-360 and WT-383 issues.

        Right now, I propose taking a similar approach that I took with the YANG Mailing List and Wiki Group, i.e. creating an opt-in contrib-watchers group. This probably isn't the final solution, but it should reduce the immediate annoyance. I'll send an email to people when this has been done.

        Please note that JIRA (like Confluence) supports watchers, who are notified of all changes to a JIRA issue. However, the bootstrap problem is how you know that the JIRA issue was created in the first place, and Atlassian groups are really the only way (well, certainly the simplest way) to handle this. But the Atlassian tools don't allow users to manage their own group memberships (Atlassian claim that it's a security issue). There are two ways to mitigate this:

        • The approach taken with the yang-watchers group, and that I will put in place for the contrib-watchers group, where a set of trusted people can be delegated (by an administrator) to have the right to add people to and remove them from a group (this isn't ideal but it's better than requiring everyone to ask me)
        • Adding a new feature to allow people to manage their group memberships (for a designated set of groups... obviously not for groups that confer privileges). We hope to procure such a feature in the near future
  7. The name should automatically include the year. Using an sequential number will just lead to very large unmanageble numbers(filenames) over time. I know jira can search on date, but its also usefull for filtering and sorting after you have done a download of contributions and the metadata is not available.

    Note also that summaries or other labels should not contain special characters like eg. ~ " # % & * : < > ? / \ { | }. , as these are forbidden for use with OneDrive cloud storage.

    1. Thanks for the comments.

      I guess the point about special characters in the summary is that it, and therefore potentially the special characters, can be included in the directory name when downloading attachments? I just tried creating a contribution with this summary:

      Summary with lots of {} and / characters!

      ...and downloading a ZIP, and I found that the special characters were simply omitted from the folder name. So I think that we should be OK.

      I'm not sure that special characters in labels will cause problems... but I do think that we're all agreed that labels will be more useful if they adhere to some naming guidelines (these guidelines will hopefully emerge organically without the need for central authority!).

      1. Thanks, I tried it using special characters in the summary of SANDBOX-4, indeed special characters are removed by the tool before inclusion in the zip. So is'not an issue to include summary in the filename.

      2. I think we should also add a guideline that file names of attachments should not include special characters, for the very same reasons Herman mentioned below: cloud storage. The files are not renamed in any way when downloading the attachments.

        1. The downloaded filenames are the same as the names by which they were uploaded, so any invalid characters in the names were put there by the uploader!

          But I agree that it would be useful to "clean" the name by removing or mapping any characters that are likely to cause problems. We could also publish some naming guidelines to reduce the chances that there are any bad characters in the first place.

          1. Re: "We could also publish some naming guidelines to reduce the chances that there are any bad characters in the first place." ==> This is what I meant!

            I hope in the future we can achieve automatic naming of the uploaded files, but we are not there yet. For the moment I would be happy with a note saying "don't use special characters" in the "hint" text when adding attachment.

    2. Moving my original comment to a reply ... I don't believe JIRA will support automatic inclusion of year, but I also don't consider it an issue. In the 20 years of BBF/DSL/ADSL Forum's existence we've had less than 20,000 contributions. What that means is that a five-digit number gives us another 80,000 contributions - let's say, conservatively, another 50 years. Five digits is less than nearly all existing contributions with the year included! So no, it won't get unmanageable.

      1. Dear Ken,

        I think you are missing the point. It not about 'technical' manageabilty. You can easily put in 9 digit numbers giving you millions of contribution space (a name with date is even longer).

        It's about correlation of a contribution number with a (quarterly)meeting.

        This data+number gives quick valuable insight on the contribution (when presented, what meeting minutes to look at, which plennary report etc..)  without going to the metadata and setting up filters. I remember contributions by the quarterly meeting we had them in. If you assume about 1000 contribution a year (now we have around 1200, should be possible now that liasons are taken out), with a flick of the eye you can map a contribution to such meeting (even interims) i.e range 0-250 1st quarter, 250-500 2nd quarter etc. In a quick search you are at most one meeting off.

        1. Well, WTs (and SDs etc.) have always broken that rule: their contributions are numbered when first created, and can then be active for many meetings.

          We can and should create (and save, and name, and share) searches that answer questions like "Which contributions from <PROJECT> have been updated since <DATE>?".

          Once we've created some searches such as the above, I think (and hope!) that people will quickly realise how to adapt and refine them, e.g. change the search criteria or add new criteria.

          1. William,

            I am discussion contributions, not WT's or SD,

            Also I am discussing off-line use, so JIRA searches do not help.

            1. OK. I meant searches to select the contributions that you're interested in, then downloading the contributions.

        2. I would prefer a convention of CONTRIB-YYYYMMSSS[S] where we have year and month of contribution, and then a 3 or 4-digit sequential number. Like Herman, I like the possibility of directly relating the contribution number to the date it was submitted.

          1. As Ken Ko said at the top of this mini-thread, this is not possible. The 'name' of the contribution has to be of the form CONTRIB-number, and the number has to be assigned automatically.

            I think that we will need to learn to live with the creation date being available only via the metadata and not via the name.

            1. Maybe everyone has now come to terms with the fact we won't have the year in the contribution name, but per the below post, Is that correct that having JIRA issue number starting with the year number would be possible by manual intervention (once a year) in the DB: https://community.atlassian.com/t5/Jira-questions/Any-way-to-set-or-seed-the-starting-Issue-number/qaq-p/405290#M169584 ? Not sure if this is feasible in our case, but I still want to bring it up, as I think this would be minimal manual intervention, and could be quite helpful.

              1. Yes we could (in theory) do this, but I think that there are some practical problems:

                • There have been several recent years where there have been more than 1000 contributions, so (given that past ARO contributions are to be imported) we'd have to reserve five digits for the contribution-within-year number, so we'd end up with nine digit contribution numbers (201700001 etc.). We couldn't use 20171 etc. because the contribution after 2017999 would be 2018000!
                • We'd need to re-number the (admittedly small number of) existing CONTRIB contributions (and fix all the references between them)

                Would we do the same for LIAISE? What about all the other JIRA projects?

                As you can probably guess, I am not in favour on doing this!

                1. Well, if it's only me, I will not insist. (smile)

  8. Will JIRA support summary email similar to what we have today with ARO. I find it much more convenient to get one email a day with everything submitted that day. 

    In reviewing the above comments it seems that in order to monitor a contribution to a group that is of interest to me I will need to manually "watch" that contribution, is that correct? Seems like you placing a excess burden on participants that have a previously known interest in everything that goes on in a specific group (say Common YANG, or SNV-NFV).


    1. A lot of features are available, and we need to decide how best to use them (smile).

      The following will be the initial setup:

      • Members of the contrib-watchers group will receive emails when new CONTRIB issues are created, so this is quite like the existing contrib@broadband-forum.org email list
      • The same people will be added to the list of watchers for new CONTRIB issues and can subsequently remove themselves at any time

      We can also define project-specific groups whose members will only be added as watchers for CONTRIB issues for that project. For example, members of the yang-watchers group could be set as the default watchers for Common YANG CONTRIB issues.

      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, e.g. it could be something like "Common YANG Updates" that lists all Common YANG contributions that have been created or updated in the last day
      • You create a subscription, 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, I've created a Common YANG Updates (https://issues.broadband-forum.org/issues/?filter=10507) search filter and shared it with everyone. You should be able to go to that URL, then click Details and select New subscription.

      We'll provide pre-canned examples of this sort of thing, but I hope that people will quickly learn how to adapt and customise them to fit their needs.

      (I should also note that, while this filter works and generates sensible results right now, CONTRIB will be cleared out tomorrow pending going live)

      1. Yes I discovered how to change the filter fields after posting my question. Thanks for the response. I believe this will work well, very flexible. I've created two filters; one for a daily subscription (i.e., summary report) and another for everything open on work areas I'm interested in. Seems very easy to create and modify a report that can be exported to excel (my tool of choice (smile) ).

        My suggestion to others is play with it a bit, Yes it's a new tool and no one likes a new tool but you might find you can get used to it.

  9. How to remove a specific version of a given contribution?

    1. Do you mean removing an attachment or removing a revision of an attachment?

      1. I have uploaded contrib .. 20006-Nokia-xxx.00; then latter, a revision 20006-Nokia-xx.01, how to remove the 20006-Nokia-xx.00 from Jira?



        1. Currently only CONTRIB administrators can remove attachments (right now, this means April NowickiMark FishburnWilliam LuptonJohn BlackfordLincoln Lavoie and Michael Fargano). We should look into adding other administrators, including AMS people... just haven't got to it yet.

          But removing an attachment is not a normal operation, right? Don't you have to ask AMS to remove an ARO attachment?

          I suggest that, if an attachment was added in error and needs to be removed, you request it via a comment to the contribution in question. If no administrator responds in a reasonable time, feel free to back up the request with an email!

          1. ok thanks, it can stay, it was just to not confuse people and to not overload the system with versions that do not need to be there.


            Christele

            1. Actually my understanding is that this should not be a normal occurrence (outside of, for example, uploading an attachment in error). Uploaded contributions are retained by BBF for legal reasons and shouldn't be deleted. 

          2. Yes, this is "Not a normal operation," it should require an admin to do it.

            1. I do not agree. A user should be able to delete his own 'erroneous' upload. We have moved from ARO to this tools because we wanted to avoid manual interventions. Now you are creating e new manual intervention.

              1. Removing an attachment is not a normal operation, it should be sufficient to make a comment about erroneous upload in the Comment field.

              2. So, what happens if an author deletes a contribution after the group has reviewed and agreed to it.  In principle, I agree with you, self service is always better, but I would only support that if JIRA actually "keeps" a record of the deleted file, otherwise we lose tracability.

                1. This can be handled trough the contribution workflow process. Deletion could be restricted to the first entry in "for review" or within a fixed time period after creation e.g.1 hour.  "Erroneous" uploads may contain confidential or other information not suited for publication, hence it must be possible to remove, if not yet handled as contribution, as quickly as possible, without going trough the bottleneck of 'administrators'.

                  Note that its very easy to do an erroneous upload, its a matter of hitting the enter key too quickly or dragging a wrong file.

                2. It should not be possible to delete a contribution already agreed to. But this will not be the case for erroneous uploads.

            2. The contribution notice says "The author reserves the right to add, amend or withdraw any and all statements made herein", so it should be possible for the author to withdraw his contribution not only logically but also physically, by deleting it. I know it was not possible in ARO without Secretariat intervention, but I don't see why we should forbid this.

              1. What happens if the author delete wrong file and not "erroneous" file? He would like to make sure all deleted files, if deleted by error, are traceable and recoverable. Or, would ask admin to restore his deleted file.

              2. the author could be given the right to manage his/her contrib, so delete as well, until the state pass to a - reviewed state , then it should not be possible anymore. I do not know if JIRA would allow such flexibility though.

                1. A contribution can have multiple attachments but has only a single state. So I'm not sure (even if it were possible ... which it might be!) that this is a solution.

  10. I guess we will answer most of the following questions step-by-step (mainly by introducing conventions), but I will already list here some things that came to my mind and I think are not fully clarified on this page (sorry if I've overseen or misunderstood something!):

    1) Is there still a convention that we MUST use a zip file if there are more than one current attachments (i.e., not revisions, but just different files)? If not, is there any way to "label" which of the attachments belong to the current revision? Or will this be done also with naming conventions?

    2) This wiki page only implies it, but the webinar made it clear that the "description" of a contribution is like the "abstract" of an old ARO contribution. However, I want to note that JIRA issues in general (including most JIRA issues in other BBF projects before CONTRIB) often contain the entire technical issue in the description without any attachments. Is this approach encouraged for CONTRIB as well? If not, I think we should say it louder. If yes, we assume that we don't care much about strict "versioning" of such contributions and we are fine with just being able to track the history, right?

    3) Have we checked if it is possible/easy to download "only the LATEST attachment OF EACH contribution from a search result list"? Do we care?

    4) I don't see an "Attachments" option under the "Export" button in the search results page (yes, I think I am looking at the right "Export" button... the upper one, left to "Tools"...). Am I doing something wrong?

    1. Thanks! Brief answers. Please note that we will definitely collect the results of all these discussions and include them in the main part of this page, or in other pages, e.g. in an FAQ. But this might take a little time...

      1) ZIP: There has been very little discussion of use of ZIP files. The only thing I can remember is that I believe someone pointed out in one of the webinars that the inclusion of the file topic in the file name is likely to reduce the need for ZIP files. They will still have a role, e.g. when wanting to attach a large number of related files.

      2) Description+comments versus attachments: I think that it's fine if the first uses of CONTRIB (since it's a replacement for ARO contributions) mostly contain the contribution in the attachments. But I also hope that individual BBF projects will be flexible in the ways that you suggest. It's really a case of "learn to walk before you learn to run". We will definitely need to return to this.

      3) Download only the latest: We know that this can't currently be done (you can only download individual attachments or all attachments). We felt that we could live with this for now, but definitely intend to provide a way of downloading only the latest versions.

      4) Export → Attachments: Sorry, there was a problem. It's working now.

      1. Ok, I understand and I'm happy with all the answers, thanks!

  11. Note that this wiki page lists the attachment filename rules (I've just updated them to include an option "author last name" field). As a reminder, the summary shown below is on the "Create issue" screen.

    We've seen quite a variation of attachment naming styles in the contributions that have been created so far. Please try to follow the rules!

    1. I do not understand why the author name should be in the filename. Contributions are company submissions, so if any name is to be added, it's the company name.

      1. The author name is optional. Individual WAs might require it to be used.

        1. yes, it might be handy to know who would present it....

          1. author and presenter are not the same thing. Issue is also when an file changes author, then also filename needs to be changed.

            1. We might not need a "one size fits all here."  In general, contributions won't "live" long enough to proceed through multiple authors.  Working text type documents do, but I don't see why we couldn't stick with the traditional naming schemes for those documents (i.e. WT-xyz_Rev-ab.docx).  

              The point is, the system is very flexible, gives some power to our users, but to help ensure things can be found when external to the JIRA system (i.e.you downloaded the file), we're asking the users to stick to a convention for file names.

              1. If the intention is to find back file off line then definetely add the date in the CONTRIB name, so you can quickly sort per meeting. See my previous comment on naming.

                A author name is something that MUST NOT be in (attachment) names. There is already assignee and reporter in Jira, as well all that information is available in the context data. As the tool downloads attachments in directories, why not add always - automatically - a context file for searching instead of creating complex filenames?

  12. The question of how to handle joint contributions arose at one of the webinars. They should be handled as follows:

    • The designated "primary contributor" should create the contribution
    • Other contributors should be "@mentioned" (i.e. formally referenced) in the contribution's description and any attached documents

    Note: to search for "@mentioned" people you need to use their usernames (which should be their email addresses). You can use a wildcard so, for example, a quick search of "sandbox wfl*" will find a SANDBOX contribution that my alter ego is mentioned in. And "sandbox mfishburn*" will find the same contribution.

    1. Two questions:

      1. With the current process, do we need to add a statement like "joint contribution supported by" (like SANDBOX-3) when @mentioning co-authors?
      2. Further question on possible improvement of the current mechanism of joint contributions. Is that correct to assume that there can't be multiple reporters in JIRA? If so, is there a way to add a field called "secondary reporters" (or similar) to contributions, where one could indicate multiple persons, so that we could have the flexibility of doing a search for "reporter = Marcin Drzymala" OR "secondary_reporter = Marcin Drzymala"? I think this would be less cumbersome than soing a text search for people's names...
      1. A JIRA issue can only have a single reporter (and a single assignee). Yes we could add fields such as those you suggest, but the feeling in TTT was that the additional complexity isn't warranted. I'm sure that some TTT members will be happy to weigh in with further thoughts on this.

        I think that something else that needs to be considered is that a contribution can have attachments, and the attachments have authors (which will be listed in the attachments). Note:

        • Listing the contribution co-contributors in the contribution description is analogous to listing attachment co-authors in the attachments
        • Nothing can guarantee that all the attachment authors are listed as contribution co-contributors (this would have to be done manually)
        1. On your last issue, I don't follow. Usual practice is that an uploaded contribution is "joint" as it will have one file that is co-authored (or supported) by multiple companies, not that it is "joint" because it has multiple attachments, each authored by one of the co-contributors.

          My issue is still with search. If I remember there was a joint contribution where Telecom Italia was a co-source, it is currently difficult to find it if Telecom Italia was not the "primary contributor".

          1. As I said, this is technically feasible. Let's get some more opinions.

        2. During 2018Q1 meeting preparation I was asked how to name joint contribution attachements. In our joint contributions we adopted the following convention:

          nnn-company1_company2_company3-[author-]title-version.extension

          And this list can vary depending on support of the contribution, so if a paper is originally written by company1 and company2, and is later co-signed (supported) by company3, the attachments would be:

          • 20XXX-ORANGE_Huawei-Some contribution-00.docx
          • 20XXX-ORANGE_Huawei_Cisco-Some contribution-01.docx

          William Lupton: Is this the right convention? Is there any guidance on this so we are consistent between the groups?

          1. Apologies for the very long delay in replying to this comment. I hadn't forgotten!

            As of yesterday, Jira contribution attachment handling has changed. Attachments are now automatically named as follows:

            key-number-company-title-version.extension

            ...where key-number is the full Jira issue name (*), company is the attacher's company name (derived from the "BBF Company" field), and title is optional. Version numbers in uploaded filenames are honored, and the file extension is always taken from the uploaded filename. See Jira Contribution Attachments for full details (and note that you can use the SANDBOX project for experimentation).

            Therefore there is no provision for an attachment name to include multiple companies (unless you play games with putting some of the company names into the title, which I don't recommend!). The uploader of a given attachment is regarded as the contributor (of that attachment), and if multiple companies support an attachment then this can and should be indicated within the attachment itself (plus it can be indicated in the Jira issue).

            (*) For contributions of type "Draft", key-number is the document name, e.g. WT-123i2.

  13. I saw some discussion of how to create links between CONTRIB contributions and 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.

    I’d recommend using 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.

    Tip: You can make a link in 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.

  14. I've created and shared a couple of JIRA filters (thanks John Blackford!) relating to Common YANG contributions:

    WADs (or anyone else of course!) might like to modify these filters for their own WAs (John already did this for BUS):

    • Go to an existing filter URL, e.g. to YANG Q3 New Contributions
    • 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
    • Click Details → Edit permissions to share the filter
    • Tell people!
    1. Is this enough information to get people started, or would more examples be useful, e.g. how to narrow to a particular PS or Project, or (as I see some people have done already) how to use labels.

      1. It would be helpful to have filters for contributions to each WA, or even better a direct link to download all contributions towards a particular WA, similar to the ZIPs per WA that Secretariat always created. I'm not sure if it's feasible though.

        1. Hmm... but I told you how to create a filter for each WA! I'd really prefer to teach people how to fish...

          Maybe we can do per-WA ZIPs for the next meeting (by which time all contributions will be in CONTRIB). It's feasible... but someone has to do it!

          1. I did create filters in the past to do just that, but they don't work anymore.

            1. Sorry, the BBF Work Area option values did change (after the first set of webinars but before the member webinars and before CONTRIB went live). The unnecessary "Work Area" text was removed. The value is now "Physical Layer Transmission (PHYtx)". You'll need to update the filter.

              I can't 100% guarantee that we will never change values such as Project, PS or WA names in the future, but I can guarantee that we won't change them without good reason and prior notification. As you have discovered, changing such values can break filters!

              I guess the conclusion might be that "we" (meaning "I" I guess) should designate a core set of supported filters that we will fix if there are any such value changes. Users would still need to be responsible for their own filters (whether derived from a core filter or created from scratch).

            2. Further to my previous comment, I have saved and shared a BBF PhyTx - Open (WL) search that everyone can access at https://issues.broadband-forum.org/issues/?filter=10803. This includes just the following fields (Key, Created, Summary, BBF Project, BBF Project Stream and Status).

              The JQL is quite simple:

              project = CONTRIB AND resolution = Unresolved AND "BBF Work Area" = "Physical Layer Transmission (PHYtx)" ORDER BY key DESC

              Having selected this filter, I can use the Export menu CSV (Current fields) option to export a spreadsheet (comma-separated values) containing just the displayed fields (which include the creation date). And I can use the same Export menu's Attachments option to export a ZIP file of all the attachments.

          2. I was able to define a filter and identify the set of contributions I wanted to see. Then I did miss a 'zip all'. Instead I downloaded them all individual. With other words: I would like the zip function to work on any selection I made through a filter, per-WA is just an example.

            1. Having defined a filter, you can 'zip all' the attachments from the resulting contributions. See the Download search results section on this page or look at offset 0:45:00 in the first JIRA Contribution Webinars video.

          3. I would hope the Secretariat could do that, just like it was done before with ARO. Gabby Bond?

    2. Thanks for the filters, that is useful.

      I am trying to create a filter to get for example all Nokia's contributions for Q3, given the name 'Nokia" is in the name in the attachment, how to do that?

      thanks,

      Christele


      1. We do have an attachment searching add-on that adds JQL functions for searching by attachment name, type or content, but unfortunately I can't make it work with attachment names of the form "20123-company-xxx" (it supports wildcards but not at the start of the string). I will look into this further (here's the documentation).

        However, I think that a better way to search for Nokia contributions might be via the contribution creator (aka reporter). Right now there is no Company field but we will be adding one (derived from the reporter). In the short term I have added a Reporter Domain field that is (for example) nokia.com for Nokia contributions. For example, this JQL searches for unresolved (open) Nokia contributions:

        project = Contributions AND resolution = Unresolved AND "Reporter Domain" in ("nokia.com")

        You can also give a list of domains, e.g.

        project = Contributions AND resolution = Unresolved AND "Reporter Domain" in ("nokia.com", "adtran.com")
        1. That is working fine, thanks

  15. I've created a filter and subscription so I can get a single summary email from JIRA on the projects I have an interest in. So far this seems to be not too complicated and works well. My only complaint (so far) is that I have no idea which CONTRIB goes with which project in the subscription email. The emailed table had the following fields:

    T  Key  Summary  Assignee  Reporter  P  Status  Resolution  Created  Updated  Due

    I'm wondering if the Project can be easily added to this summary email? OR, more broadly, is there a way to control which fields are included in the subscription email?


    1. Yes you can do this (it's part of the filter definition). See this Atlassian Changing the column configuration for your own filters page. You can also delete columns and change their order.

    2. 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)). 

      1. I am also confused. I use some filters created by others. You say that "Once you've loaded a filter, if you change the column settings, they take immediate effect. There's no need to save them", but it doesn't work for me as it says I don't own this filter. See here:

        Is the only solution to clone this into a private filter and reconfigure the columns then?

        1. The filter's column settings are part of the filter, and I don't think that anyone (even an administrator) can change someone else's filter. So yes, I think that you need to clone the filter (or ask the owner to update it).

  16. Notifications were discussed earlier (above) but that pre-dated the CONTRIB launch, so I'd like to give a brief update / reminder.

    Firstly, if you want to be notified when new CONTRIB contributions are created, you need to be in the contrib-watchers group. Right now, you can't add yourself to this group (this is an Atlassian restriction, but an 'add-on' to permit this is being written and should be available soon). In the meantime, several people are able to add you (not just me) and you can see details on the Jira Contribution Notifications page.

    If you are in the contrib-watchers group, then in addition to getting an email when a CONTRIB contribution is created, you will be added the the contribution's "watch list", and will receive emails when the contribution is modified in any way. If you aren't interested in the contribution, simply go to it and remove yourself from the watch list.

    If you prefer a "digest" style of notification, e.g. once a day, then you should look into subscriptions. The basic idea is that you create a filter that contains a time criterion such as "modified in the last day" and then create a subscription to run that filter at a given frequency. These subscriptions are discussed earlier in this page's comments.

     Click here for some more related information that might be helpful...

    Right now (be warned!) you will probably get more notifications (per contribution) than you might want. We will try to tune this better… but there’s always going to be a balance to be found between too much information and missing something important

    Notifications are driven by event types (issue created, issue changed, attachment added, comment added, ...), not by filters (use subscriptions if you want to fine-tune notifications)

    I am working on including better information in email subjects and bodies, e.g some time soon the email subject line will indicate the WA and probably also the PS and Project. This should make it easier to filter the emails

    1. I would like to add a precision (maybe helpful for some) that as soon as you are subscribed to contrib-watchers group, you will be added to contribution's "watch list" for any new contribution, but this won't be retroactive, so you will not be added as a watcher of contributions created before you were subscribed to the group.

      1. Correct. For that I suggest using a bulk operation if you want to watch multiple contributions (as usual, do a search first to find the contributions of interest, then do the bulk operation). Search this page for 'bulk operation' and you will find some links.

  17. Two minor things:

    • Apparently there is no way to show the "Issue Type" (e.g., "General Contribution", "Draft") with text (instead of an icon) in the search results. I personally find this information very useful. I guess we could do one of the following: 1) find a way to enable showing "Issue Type" either as icon or as text (possible?), 2) don't assign any icon to the issue types of BBF contributions (General Contribution, Draft, SB comment, Other) so that the respective text appears automatically in the search results, 3) make Issue Type always ="BBF contribution" (with the current icon) and create a separate field to hold the information about the contribution type, 4) ignore my comment
    • I noticed a case in which the "Reporter" (i.e., contributor) was a username instead of a full name. I think it would be good to make sure that "real" names appear always. But I guess this is very minor, since I saw it only once.
    1. Thanks! Here are my thoughts.

      • Issue Type display
        • Another thing that might help (and maybe we should try first) would be to use easily distinguishable icons for the issue types
          • I was lazy and used the same one for all of them; suggestions for new icons are welcome!
        • Based on this page, it looks as though this is controlled by explicit code (so-called velocity templates) but I will take a more detailed look
          • I don't think that removing the icon would work; I think that the column would just show nothing (but I guess I could try)
          • We could change the velocity code to include the text (the changes are actually similar to some changes I am making to notification email subjects and bodies)
          • If we did change the code, I might be tempted to do the same for the Priority field (I'm colour-blind and can never tell which is which of Highest/High and Low/Lowest!)
          • These changes (unless we make them more complicated) would be global and would affect all JIRA query results
        • We want to use this standard field for all contribution types, so I don't think we'd want to move the other types to a separate field
          • We could define a separate read-only text field (a so-called scripted field) with the same value as the issue type field, but I don't really like having two fields with the same information (however, this would be pretty easy)
      • Reporter anomaly
        • The user details didn't include the full name. I found and fixed this. I do need to go through and weed out such anomalies (e.g. there are some usernames that aren't email addresses)
      1. I dislike the idea of using Icons. As I've mentioned above I will probably be importing filtered results into excel for my own tracking and sanity. Icons will get removed as they cannot easily be associated with a record in excel and cannot be sorted/filtered or otherwise processed. Would it be that difficult to create a text filed that is auto-filled?

        Yes Icons look nice and flashy in a report generated in JIRA but are somewhat useless once downloaded.

        Just my 2 cents.

        1. If you save search results as CSV you get the issue type text ("General Contribution" etc.). Not an icon in sight.

          Is there a particular field where an icon prevents or complicates auto-filling? In general such things can be selected from an option menu (which supports auto-complete).

  18. This may have been mentioned in the webinare but is there a list of field names somewhere? The dropdown lists are great but typically only show a small number of names and if you've no idea what a field is called it's difficult to poke around to find it. Seem like this should be part of the basic documentation/user instructions (for folks like myself that are not as familiar with these new fangled tools as William is).

    TIA

    1. Yes I think this did get mentioned but I don't seem to have created a corresponding action. I'll make sure to do this (at some point). Thanks.

  19. In ARO for searching and overall assessing who/what company contributed to what I found very useful to have the fields Author and Company.

    In creating my contributions, when multiple co-signers where involved, I took advantage of the free text format to introduce all co-signers names under "Author" and the related company in the other field.

    I'd like to propose to reinstate that practice, rather than having the authors being added in the Abstract text which is not visible in a List view. Then I agree the authors names should be introduced, given this is possible in the Wiki, via @mentioned (per William prev comment) rather than in free text.

    I enjoyed very much the field Company reported in the Manifest.csv created  by ARO to tag contributions into my PC also using 3-letter mnemonics for the company name. Having this ins an Excel file summarizing metadata is the most effective way to post consume these metadata. The CSV currently produced with commas is difficult to report to the nice tabular format that is graphically shown on the web output of a search.  At least having the Company name in this graphic output would help (rather than doing the association between the Reporter and the presumably known company)



    1. Just to check that I understand, I think that you are proposing a new Author field that would be a list of all the authors (probably defaulting to just the reporter). If we did this then I think that the Company field could be automatically generated from the Author field (rather than, as currently planned, from the reporter). Have I understood correctly?

      1. Correct William. I forgot to mention above that using an Author field hardwired to the list of delegates with login "forces" any new individual participating to a contribution to get a login ... and the tribe grows!

        I see the value of generating automatically the corresponding company field rather than free format. There may be side effects though: the company name may have been filled from the BBF formal database with full name (e.g. Nokia Telecommunications, or Telecom Italia S.p.a) which may become a little cumbersome but clearly this can be overcomed if instead a tag name (just Nokia or TIM) are fed into the Company field coupled to any delegate record. Moreover then, such Company field could be conventionally limited to just no more than  3 (or 5?) upper case characters: Nokia = NOK, Huawei = HUA, Adtran = ADT, UNH, TIM, BT, Orange = ORG, etc.

        The other side effect may be that when multiple delegates of the same company authored the contribution a dumb rule like "fill Company field upon each entry in the Author field" would lead to e.g.: Huawei, Huawei, Huawei, Huawei, TIM, TIM, UNH, Nokia, Nokia.

        Once again I assume a clever auto-fill rule could be implemented instead of the dumb one.



        1. I was assuming that Author would be initially (automatically) populated with the contribution creator (=reporter in JIRA-speak) and that any additions would be manual. So I don't see a problem with the tribe growing.

          Yes, I was indeed imagining that the company names would be standardised (maybe including complex punctuation and country-specific suffices such as "S.p.a"), but these wouldn't be free text, they'd always be selected from a pre-defined list (like the Projects, PSs and WAs already are). So you should be able to type "Nokia" (or  whatever) and quickly find the right company. Yes indeed short versions might be useful (like we already have for Projects and WAs, but not currently for PSs) but we'd have to agree on them!

          On the last point, I think that we can avoid duplicates in the list of companies! For example they could be treated as a set and presented with the contribution creator company first, followed by the rest in alphabetical order.

  20. Another ARO feature is assigning to more than one Work Area. This is usefuls to give visibility a contribution is relevant for more than one WA and implicitly trigger the involved directors to consider holding a joint session.

    Furthermore, by the email notifications mechanisms it exposes members typically checking their WA of interest of that contribution in push mode. And then when they would get to download contributions via filtering by their "favourite" WA they would see that contribution in the list. E.g. if a contribution is primary for SDN-NFV but it has a content of interest for FAN, if only one WA (hence SDN-NFV) can be selected in the metadata a member usually following only FAN will hardly be "exposed" to it.

    1. This is already supported (you have to hold CTRL while you click), but both work area and project stream are multi-select.  

      1. It must also be possible select multiple projects, which is not the case today.  PhyTx We have contributions applying to several WT's, but there is no way to indicate that without using labels.

        1. TTT's has discussed this and we're not convinced of the need for it.

          1. This came up again at the session today. It is strange one can have a contribution towards multiple WAs, but not towards multiple projects of the same WA. The only workaround we see is to copy-paste the contribution for another project, which makes little sense IMHO.

            1. I'm not convinced it needs to be a multi-select, because it will make the agenda much hard to prepare, because I don't think we want things discussed multiple times.  I agree we likely need to "cross link" stuff, so other projects are aware of a contribution.  However, if we allow multi-select for project, the result would likely be, any automated agenda preparation we could create/use would list contributions multiple times (in different projects), and I don't think that is what we want.

              1. I agree with you Lincoln. Maybe a solution would be to introduce a field called "BBF Secondary Project" (or "BBF Related Project")? This way there always is a primary project (for agenda setting purposes), but if you want "not to miss" some contribution that has impact on another project, you can do a search for "BBF Project" = x OR "BBF Secondary Project" = x. Also, this is easy for the secondary project to do a search for related stuff.

                The alternative solution I've seen somewhere of using labels is IMHO not elegant, as it forces you to repeat the same information in the label.

  21. I find very useful that the zip file containing downloaded contributions allow to name them by piping contribution number and title.

    I find less practical the fact files are put into folders: when I extract them into a destination dir files are not in a single list for immediate consultation (especially of properties), they are one click more away for consultation and the overall path gets 20-40 characters longer which may pose a problem with path length limits on popular cloud storage services.

    Is there a way of putting the downloaded files into the root of the zip archive?

    1. I agree with you that the directories are cumbersome. Also the directories are only created if you download multiple CONTRIB. If you are interested in a single CONTRIB then the directory is not created and you have to download one by one and create the directory yourself. So it should be possible to download a single CONTRIBs attachment also in driectory structure

      Alternatively, although I understand William wants to move away from Zip, what is the issue with just creating a Zip per CONTRIB, wihout adding a directory structure on top? The Zip would have the contrib name. You could take this further and introduce renaming as in aro, a single attachment would be the root file (contribxxx.doc, ..), multiple attachment would be converted into contribxxx.zip (with or without renaming of the attachments)?

    2. The current mechanisms for downloading contributions are off-the-shelf features and "they are what they are". Let's use this conversation (and similar conversations) to 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.

  22. Mmm, not sure if I understand all the options you are describing though I'm a bit scared about generating multiple ZIP files. As mentioned I like to extract all contribs (say per meeting&WA) into a single dir to open them immediately and to consult them and their properties with Windows explorer. Having one ZIP per contrib would force me to do multiple extractions.

    Furthermore the packaging multiple contributions in a ZIP (after doing a search) goes with the associated action of extracting their metadata (though I'm not fully happy with the current formatting of the extracted metadata) which I typically use for a little of post-processing of files properties exactly to improve the immediate consultation of contribs properties  (mainly a 3-letter company tag info) as mentioned above. 

    1. Wrt to my initial input on this sub-thread I have realised that only the folder name in the zip takes the contrib number and title. While I see file names with name as originally assigned by author and others with 200xx-title (maybe this was the actual name given by the author).

      It would be great if the file itself was automatically named, upon upload, per this conventional naming structure (# + title), regardless of the actual file name. And at this point we could (try to) get rid of the folders in the zip.

      I also noticed that the revision # of a contribution is appended at the end of the file name, which makes it less readable once on my PC, as oppose to bbf2017.nnn.rr, i.e rev number appended right after the contribution number in the file name.

      An easy way to unify attachments file names is to ask authors to upload them with this format: "200xx.rr title.doc" or even "C-200xx.rr title.doc".

      Views?


      1. Right, the current variation in attachment names is entirely down to the authors (sad). We have discussed (and would like to do) automatic naming (to the extent possible) but don't currently know how easy this is to implement.

        Putting the version number earlier hasn't been suggested before. I take your point, but do please note that the version number refers to the attachment and not to the contribution (however, read on...).

        There has been some discussion of automatically generating the title part of the filename too (from the summary). This would mean that all attachments to a given contribution (apart, possibly, from the company-name and author-last-name - if present - fields) would have the same title part (unless, I suppose, the summary was changed during the lifetime of the contribution).

  23. Further ideas on the mechanics for downloading contributions (not really replying to any reaction above).

    Along with using filters to narrow down the overall list of contributions, it would be very useful then to pick and choose just some contributions via a tick-box selection (with the usual select-all/deselct-all buttons. Then the user could launch the Export on this subset of chosen contribs.

    1. This is a good idea! But I don't know whether it's possible. However, you could try doing a bulk operation to add a personal label such as mauro-temp. With this approach you do get the option of tick-box selection. Having defined the label, clicking on it (or including it in the search) will select just the contributions with that label (which, if you like, you could remove once you're done with it).

      This Working with search results page has some good general information, and includes a link to this Editing multiple issues at the same time page. Note that you have the option of disabling the sending of email notifications for bulk operations (and it might be kind to do this).

      Let me know if you need more info. By the way (PLUG!) this is just the sort of thing that I could demonstrate at the Wednesday 7am training session!

    2. In my way of using CONTRIB, I find the lack of check boxes in list view (for attachment export) the single most missing feature of JIRA. For instance I would like to quickly look at all contributions uploaded, and based on my judgment (not any specific search criterion), decide which of them I want to download. Currently I think I'm only able to download all, and then manually delete those I am not interested in.

      1. I don't know of a way of doing this, and my suggestion of using a temporary label is the best that I can currently offer. Sorry!

  24. This is a high priority request, hopefully swiftly doable: integrate in the built-in filters bar the one for "BBF Work Area". This is a primary search filter and we don't one to have is "buried" in the "More" list, i.e. one additional click away.

    1. Unfortunately I don't think this is possible. Note (by the way) that when you search you are searching across all JIRA projects. We are concentrating on CONTRIB (and LIAISE) at the moment, but there are many other projects. So it's not obvious to me that a field that applies to only one such project should be permanently displayed.

      Perhaps, as you get used to the JIRA search facilities, you will find that you use the advanced search more? JQL is actually quite simple (really!), and you get a lot of context-sensitive assistance. For example, starting with a quick search for contrib, and clicking Advanced, you should see this JQL:

      project = CONTRIB

      If you now type "and bbf" (case doesn't matter) you will immediately see an option menu with the matching field names and can select BBF Work Area. Having done this you will see this:

      project = CONTRIB and "BBF Work Area" 

      Now you are presented with a list of valid operators. Select "=" and you will see an option menu with all the WA names. Again, you can start typing to select the WA, and might now see this:

      project = CONTRIB and "BBF Work Area" = "Broadband User Services (BUS)"

      You will also see a little(tick) icon to the left of the JQL, which indicates that the expression is complete and valid (even though, as you can see, you could keep going to further modify the search criteria or choose how the results will be sorted).

      Now you can type Enter to submit the search, or you can click Basic to return to basic mode (note that only simple "A and B..." JQL can be represented in basic mode).

      1. Thanks for the tips William.

        Rather than retyping thislargely recurring filter, wouldn't it make sense to create once and for all a filter like:

        project = CONTRIB and "BBF Work Area" = "not assigned"

        All users could be subscribed to it in bulk and have it appear than in their favourite filters list on the side bar.

        Then at each use, "not assigned" would be substituted by the WA of interest for that very search.

        1. Try this:

          https://issues.broadband-forum.org/issues/?filter=10843

          I believe that it will not automatically be added to your favourites so you'll need to do that (click the star) and then it'll be in the list on the Issues menu.

          Let me know if you want anything changed, e.g. different columns or sort order.

  25. Can the company name be added to the reporter name in the meta data? The company name is more relevant than the reporter.

    1. It will be! See the earlier discussion from around September 6th.

  26. Hello,

    I have gone through all comments here to understand where we are, and I'm commenting in the respective mini-threads where applicable. I have also a few other questions I couldn't find answers for:

    1. Would it be implementable to have more conventions for naming folders when bulk-downloading attachemnts? My favourite would be "WT-xxx Contrib-xxx name", so similar to current Issue key + Summary, but with addition of BBF Project at the beginning.
    2. When creating a contribution (Create Issue dialog box), is there a way to know the issue number, so one can upload an attachment right away with the right numbering convention? Otherwise I have to save (Create) first in order to know the issue number, and only then attach the file. Or am I missing something?
    3. [Joint contributions] When naming attachment files, the current convention for the company is <one word company name>. In case of joint contribution, should it be the company name of the "primary conbtributor" or do we foresee multiple names here?
    4. [Joint contributions] Related question. When a co-source adds a proposed revision of an already uploaded contribution, should <one word company name> in the attached file indicate his company or the "primary author's" company name? I would guess the latter but it is a bit weird.
    5. Is there a way to assign multiple people when changing contribution state to "needs work"?



    1. Quick responses (using the same numbering):

      1. We are using a third party add-on for this and I don't know of a way to (further) customise it. I think that the likely resolution here will be to use a different mechanism (to be specified and procured by BBF) for downloading attachments, e.g. one that will download only the latest versions, and will include other data related to the contribution
      2. I hear you! My preferred solution here is to automatically include the issue number, company and version, so you'd upload myfile.doc and it would be renamed (on the server) as something like 12345-Orange-myfile-00.doc
      3. I think that it has to be the company name of whoever uploaded it (hopefully to be derived automatically). Authors need to be listed inside the attachment
      4. Well, if the company name is derived automatically from the uploader, then it'll always be the uploader. We do need to decide how version numbers should work in this case
      5. No, we are using the standard assignee field and that's one person 
      1. Thanks William, that's helpful.

        On issue 1, the best would be to be able to customise those download options. If it's not possible, then my preferred convention would be to have either 1) all files downloaded in a single folder, with the following names BBF_Project.CONTRIB-number.Reporter_Company.Reporter_Name.Title.Rev (see picture below), or 2) files downloaded in folders with BBF_Project name, and then the convention CONTRIB-number.Reporter_Company.Reporter_Name.Title.Rev.

        On issues 2-4, I am also very much in favour of automatic naming of the files when they are being uploaded, and - whetever the convention we adopt - it will be consistent throughout the attachments, which is great.

  27. As some of you may already know, we will be upgrading JIRA next week as a precursor to loading all the ARO contributions into CONTRIB. This will involve a small amount of down-time, and a message informing people of this upgrade (and the expected timing) will be sent out soon.

    I've made a couple of minor changes to CONTRIB in preparation for this upgrade:

    • A lot of additional BBF projects have been added to the list of projects. You will notice that, when you create a CONTRIB issue, selecting the BBF Project will now automatically select the corresponding BBF Project Stream and BBF Work Area (you can then select additional Project Streams and Work Areas if necessary)
    • The "from" addresses for JIRA notifications have been reverted to "jira@broadband-forum.org" (previously CONTRIB notifications had a "from" address of "jira-contrib@broadband-forum.org"). We've reverted them because there will now be additional information in the email subject lines

    Once the upgrade is complete you should immediately see that JIRA email notifications for CONTRIB (and SANDBOX, and LIAISE) include some BBF-specific information:

    • The subject line will indicate the Project (WT-xxx), Work Area, and some more information about the event type
    • The "issue created" message body will include all the BBF-specific

    We hope that this additional information will make it easier for you to create mail filters to select the notifications in which you are most interested. See below for some examples that show you how the new information will be presented.

    Finally, shortly after the upgrade has completed, all the ARO contributions will be uploaded into CONTRIB-1 through CONTRIB-18895. This will be done on the live system and may slow things down a little... but we'll be sure to do it during a period of expected low usage.

    Here are the email subject examples, one for CONTRIB and one for LIAISE.

    BBF-JIRA {WT-181} [BUS] [PHYtx] (created CONTRIB-xxx) Example to show new info in email subject
    BBF-JIRA {3GPP SA5} [BUS] (created LIAISE-xxx) Example to show new info in email subject
    1. Useful improvements, especially auto-complete of WA and PS. Thanks!

  28. Should we wait until after the upgrade before uploading contributions for New Orleans?

    1. No. Sorry, I should have made it clear that the upgrade (apart from a small amount of down-time) will affect only the currently-unused CONTRIB 1-20000 range. The 20001+ range that we started using before Helsinki is unaffected and new contributions will continue to be assigned numbers in the 20001+ range.

      There's no reason to hold off on creating new contributions for New Orleans.

  29. I am pleased to announce that all ARO contributions have now been added to CONTRIB. CONTRIB-1 through CONTRIB-18895 were originally ARO contributions and all have an "External issue ID" field that is the "bbfyyyy.nnn" string. You can search on this field if you want and can even simply type it into the search box at the top right (assuming that CONTRIB is the current project). For example, you can search for "dsl2003.304" to find my first ever contribution.

    Note: This works because this is a "text" field. It doesn't work for Projects, PSs and WAs because these are selected from fixed sets of options (so the database doesn't contain the Project name etc.). To search for these, use the "BBF Project", "BBF Project Stream" and "BBF Work Area" fields.

  30. William,


    I have tried several time to upload a contrib with no success, (contrib 20217), it says error, contact your administrator. something I should do? name incorrect?


    Thanks


    1. Hi Christele,

      Mark has just posted a notice about recent issues with JIRA uploads. I believe this is being investigated right now.

      1. Yes. Our hosting company is aware and is actively investigating. There is also a problem editing wiki pages. Hopefully there is a common cause.

        1. I believe that everything is back up and happy again. Sorry about the disruption.

  31. I have created a Jira Contribution News page and hope to add more information to it tomorrow.

  32. I've put some of the discussion here into a new Jira Contribution Tips page. I got a bit bored towards the end...

  33. I don't know if this page is still watched, but I have a question:

    Has there been any discussion about the fact that all JIRA contributions on the agenda appear with the same "Update Date" before the meetings?

    I cannot find a way of ordering them based on the "actual" update date (i.e., the date when their attachment or content was updated, and not just a label).

    1. I saw the update, so I expect others did too.

      We could argue over the definition of the word "actual"! I think that the "updated" field indicates the last time that the issue was updated, i.e. the last time that any of its fields were changed. Comments and attachments are just fields (admittedly quite complicated ones).

      I believe that results can be sorted only by the value of a field and I'm not aware of any "last attachment upload date" or "last comment create date" fields. Maybe suitable custom fields could be added.

      Note: I'd like to encourage use of the TOOLS JIRA project for tools-related discussion.

      1. Thanks for the response and the info, William.

        Since your explanation has made it clear that there is no "tool issue" to discuss, I respond here (and not in TOOLS).

        Now the remaining point to discuss is that the addition of the "agenda" label practically prevents us from being able to meaningfully order issues by "update date" since they all have the same "update date" (for the definition of "meaningfully" we could also argue, but I think you understand my point). I fully understand that the addition of this label might be much more important than the feature I am talking about and I am not requesting to change it if this change would cause more problems than it would solve. I just reported it because someone might have better ideas than me about how to address this (with you being my big hope (smile)).

        If you think that it makes sense to create a JIRA issue in TOOLS or any other project about this, I will do it, otherwise we just drop it.

  34. For what it's worth, I also ran into this issue, expecting to be able to use the "updated" field.

    1. The "updated" field is a blunt instrument. But all the necessary information is available in JIRA. The best bet is probably to add suitable custom fields (if we can't find a plugin that already does what we need).

      do recommend creating a TOOLS issue to discuss the problem, the requirements for its solution and (hopefully) its eventual solution.

      1. Ok, I'll create one, thanks!