In software development, “issue” is the general term for Enhancement Requests, Bug Reports, and Questions.

SmarterApp is the brand and community centered on the open source assessment system used by the Smarter Balanced Assessment Consortium. As Smarter Balanced transitions from the initial development phase into the operational phase the community needs a coordinated way to collect and manage issues. Smarter Balanced has selected GitHub as the repository for source code, specifications, and documentation. Therefore, it makes sense to use the GitHub Issues Management feature as well. This guide will to help you get started reporting and viewing issues.

See the GitHub Issues Guide for Detailed documentation on the GitHub issues feature. True to the open source ethic, there are numerous open source tools for managing GitHub issues, downloading them into spreadsheets for sorting and reporting, automated triage, and so forth. We’re starting with the basics.

Standards of Behavior

As an open source project, the SmarterApp issues repository is open to public view. This is an important principle of open source development followed by nearly every successful open source project. Because the information is public, Smarter Balanced expects a high standard of conduct. Contributors should not be shy about reporting issues, but all descriptions should be accurate and professional with a focus on the software and the issue at hand. Contributors should use appropriate professional language and should refrain from derogatory comments or ad hominem attacks.

Smarter Balanced moderates the issues management forum and will remove postings that do not meet these standards.

Viewing Issues

Since the issues are public, no user account is required to view them.

1. Browse to https://github.com/smarterapp. A list of projects and their descriptions is displayed. Please note the smarterapp.github.io project. This is the source to the smarterapp.org website. It’s the appropriate place to post issues associated with the specifications or documentation on SmarterApp.org.
2. Click on one of the projects (known as “repositories” in Git parlance).
3. Click on the “Issues” icon on the right side.
4. A list of current issues is displayed. The search box allows you to search for keywords or filter by various features. You also have sorting options.

Creating a GitHub Account

Before you can contribute a new issue or comment on an existing issue you must have a GitHub account.

1. Browse to http://github.com
2. Click on the green “Sign Up” button in the upper-right.
3. Choose a good username because that’s the name that will appear next to any issues or comments that you report. Most people choose a username that they can take with them when they move between organizations.
4. GitHub will send notifications about issues you report to your email address. You can change your email address and/or add a secondary email address later, after you create the account.
5. Choose a “free” plan.
6. Click “Finish sign up.”
7. The survey and tutorials are optional and are mostly oriented toward managing new projects. If you’re primarily in issues, then skip directly to the dashboard.

Enhance Your Account Profile

Since people will be reading issues you report, it’s helpful for you to update your account profile so that others know more about the source of these issues.

1. Click on the gear icon in the upper-right to access your settings.
2. Upload a profile picture if you choose.
3. Set your full name.
4. Most people choose NOT to share their email address publicly.
5. Enter URL, company and location if you choose.

Set Notification Options

1. In the Emails tab you can add email addresses. For example, you may choose to be notified at both your work and personal email addresses.
2. Any email address you include must be verified by clicking on a link that will be sent to you.
3. On the “Notification center” tab choose which notifications you want to receive.

Reporting an Issue

1. Browse to http://github.com/SmarterApp
2. Select the project for which you want to report an issue. SmarterApp has provided the “Practice” repository in which you can report fake issues to experiment with the system and get comfortable with how it works.
3. Click “Issues” on the right side.
4. Click the big, green “New Issue” button.
5. If you haven’t already signed in, you will be prompted for your username and password.
6. Enter a title and a description for your issue.
7. Click on “labels” on the right and choose the most appropriate for your issue. The most commonly used are “bug” and “enhancement.”

Issues that are reported clearly and succinctly will receive better attention. Here are some important tips:

• Make sure your title is specific and easy to understand.
• Include images or screenshots if they will help communicate the issue better.
• For bugs, include specific re-creation steps.
• For enhancements, it’s more effective to describe the user’s need, often in the form of a “user story”. Too often enhancement requests are proposed solutions. But the best solution may not be the first one that’s proposed.

As of Fall 2018 the Smarter Balanced Test Delivery System (TDS) is no longer supported.

The code base and documentation for the TDS is available within the Smarter Balanced GitHub repository.

---

Unless stated otherwise, all content on SmarterApp.org is licensed under a Creative Commons Attribution 4.0 International License.