Conducted by Aaron Zeckoski, Unicon, Inc and Neal Caidin, Apereo Foundation
Notes by Janice Smith, Three Canoes
Webinar recording at -
Both speakers have been using Jira quite a lot in their work with Sakai. This session will focus more on practical aspects of using Jira.
Jira along with Sakai Confluence and the Sakai listservs are the main communication tools for Sakai users. Jira is hooked up to the code repository system so that code changes are tracked. Through Jira work on the Sakai code is reviewed and tracked.
Confluence (aka Sakai Wiki) – https://confluence.sakaiproject.org
Email lists – http://collab.sakaiproject.org
Sakai Jira Guidelines page in Sakai Confluence is a great reference and resource.
Sakai Jira Guidelines – https://confluence.sakaiproject.org/display/MGT/Sakai+Jira+Guidelines
Use case for Jira: What if you find a bug in Sakai, what do you do? These are the recommended steps for working with a Sakai bug.
- Reproduce the bug. See if you can recreate it again.
- See if someone else has reported it. Search Jira to see if a Jira is already available.
- If you find a Jira issue on the possible bug, keep track of it, notice its status. If the issue has been fixed, you can ask local support staff or your hosting provider to implement the fix. Whether they can accommodate your request will depend on factors outside the scope of this presentation.
- If you don’t find the issue in Jira, then we recommend that you contact one of the Sakai listservs like the Dev list (firstname.lastname@example.org). (Go to http://collab.sakaiproject.org/mailman/listinfo to review all the list possibilities and view the archives for any particular list.) Start with Dev list if you are not really sure. It has the largest set of users. If the issue is very production-oriented (performance, deployment issues, rather than code oriented), try the production list. Do this especially if you are running prerelease code or planning to run it. (The Sakai lists are being trimmed down at this point to help people know which lists to approach.) There are also a few other specialty tool lists, like the portfolio list. When you post to a list, others may already be familiar with it. Someone else can find it on Jira perhaps. Others may be able to reproduce the issue. They may advise you on it.
- After you have done all of the above, then you are ready to open a Jira ticket.
- Use Google with special “site:” operator – Example to search Jira on the terms “sort order” - site:jira.sakaiproject.org sort order
- To log into Jira itself go to http://jira.sakaiproject.org . If you don’t have an account there is a link on that page you can click to get one.
- Jira keeps track of recent issues, so you do not need to go through a recent search again. Look under the Issues menu.
- Quick Search box – use this option to quickly search all of Jira on a text string. Not always desirable because you normally want to limit your search to a particular project and mostly that will be Sakai (“SAK” in Jira).
- Jira has some sophisticated text searching capabilities. The Quick Search box will create a search like this : If you type “sort order” into the Quick Search box, it generates the search: text ~ “sort order” . With the “text” search the Summary, Description, Comments, Environment fields and all text-based custom fields are searched. Probably using text or summary will cover most of your text searching needs, but if you want to explore details - https://confluence.atlassian.com/display/JIRA052/Performing+Text+Searches
- Jira has a built in capability for searching. It builds a query for you (Basic mode). You can go in and tweak the query (Advanced mode).
- Most issues will be listed under SAK for Sakai project. For most of core functions in Sakai, search this category.
- You can also search Samigo (SAM). The general code clean-up for Sakai includes a Jira clean-up. We are rolling up a lot of the projects into SAK. Eventually there will be only three or four projects in Jira: SAK, SAM, Kernel (core code of Sakai), a few other highly managed projects
- Ask questions about your search or about which category to search on Sakai Dev list
- For the field for Issue Types: select all.
- For the field for Status, go to Jira guidelines to understand the workflow filter. It depends on what you are looking for. If the issue is a bug, it may have already been fixed for a particular version. You may want to start with looking at all the statuses of the issue.
- The Assignee field will indicate the person who is assigned to work on the issue.
- There is an Advanced node with other fields including custom fields. Probably the most common of these field is Component (Assignments, Gradebook, etc).
- Affected Version indicates whether the issue affects a particular version.
- The most important field may be Component. Use this field for searching around a particular tool. There are a whole bunch of components (tools) to select from.
- During this time, Jira is building the search for you. If comfortable with queries, might feel comfortable customizing the query. JQL (Jira Query Language) has some similarities with SQL (a database standard query language).
- You can also limit your search by time. For example, if using Advanced search, you can add something like : AND updated > -180d : to your JQL query will search for tickets which have been updated within the last 180 days.
- You can search by tickets that you have reported using the reporter.
- Jira has a type-ahead function. It knows what the valid fields are and inserts them for you.
- You can narrow down your search by adding more criteria, including using AND and OR and parenthesis to group your query.
- You can always start over with searches.
- Save As allows you to save a search as your own private filter. You can come back later and use the filters you have saved. Administrators can make these saved searches public. This is an easy way to pre-can the search for yourself.
- If you comment on an issue, Jira will notify you of changes.
- If you are the reporter of an issue, Jira will notify you of changes.
- You can click on “Watch” an issue, Jira will notify you of changes.
- When you comment on a ticket, you can chime in with your experience. All the people who are tracking (watching) the will be automatically be notified. You will also be automatically added to the watch list and will be notified of any changes to the issue. You can “unwatch” a ticket at any time.
- Do this after you have verified that this is a new issue.
- Use the Create Issue button in upper right hand corner.
- Make sure it is the right project, probably SAK (Sakai CLE)
- Create a summary in plain English, short and clear
- For Component, indicate the tools that have been affected
- Affects Version indicates the version in which you found this issue. It is helpful to people who are testing it. If they are testing in a newer version, they might find it is already fixed, or they might find that it also affects other versions.
- In the Environment field, list the OS, browser type and version of Sakai in which you found the issue, indicate whether your instance of Sakai is hosted or an institutional implementation. You may want to test on a Sakai “nightly” server or QA server to see if the problem is in core Sakai or your local Sakai. If you are testing on Trunk, please include the revision number.
- For Description, write in description with as much detail as possible.
- Steps to Reproduce can be incredibly helpful in helping others reproduce it. It will help you get attention for your issue and help the community to resolve it. Screenshots would be very helpful.
- If think you have run into a security issue, then write to email@example.com before you post anything to a listserv. The security team needs time to address issue before it becomes public.
- If not sure how to create a ticket, relax and just do your best. Everything is editable. Someone else looking at your ticket can correct the issues. If you set the priority wrong, for example, others will correct it by editing it or writing a comment on the issue. Don’t worry about this. Opening up issues is vital even if you don’t do it perfectly.
- Ideally, Steps to Reproduce will include images, screenshots, URLs, error messages, logs, stack traces (which indicate a real issue with Sakai, usually among the highest priority to fix!), and environment information. All of these are very helpful for reproduction. You can attach these items as files. If you include log information, please include just the section of the log that indicates approximately when the error happened. It is almost impossible to put too much information in a Jira. It is easy for viewers to ignore detail if it is not needed. The greater danger is not to put enough information into Jira.
- You can always come back and edit or add additional comments.
- Use Attach Files for screenshots (not Attach Screenshot option). Access from the “More Actions” button.
Versions of Sakai on Nightly Servers
- Go to http://nightly2.sakaiproject.org
- Trunk is the latest version of Sakai. Test there to see if your issue has been resolved. Include revision number of Trunk in your Jira issue.
- The more places you and others test, the better.
- Jira documentation – Atlassian – provides the support for Sakai Confluence and Jira
- Very extensive documentation is available for more complicated searching and viewing.
- Will use Jira to manage the project. Currently other Apereo projects are using a different instance of Jira (different URL).
- Will it search the comments? Yes. It searches all text fields in the ticket.
- Uses a more rigorous approach to Jira that will go beyond this session.
Getting Others to Pay Attention
- Sometimes it is difficult to determine who is responsible for responding. (Remember, it is an open source community, not a commercial entity with paid staff.)
- If feel like an issue is critical, give it a few days, and then bring it up on the lists to draw attention to it. This will help get it addressed.
If there is a bug in Trunk and in a version as well, should we mark it for merging?
- If you feel that it applies, feel free to mark it as merge. Others will review the ticket and verify that it is appropriate to merge. It won’t slip by. It will make others pay more attention to a possible merge.
Sakai is a volunteer community of testers and developers. There is no development staff with an automatic process. Instead, we have people who care and have vested interests that are willing to respond to the lists and work on the project. It is important to remember this. Take advantage of community and give back as well. A big thanks to all who volunteer!