Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: replaced missing images

To

...

evolve and grow

...

Ed-Fi data exchange standards and Ed-Fi Unified Data Model (UDM), community input is essential. This page describes how to participate by submitting new ideas and tracking the status of existing suggestions.

...

Table of Contents
maxLevel1

Ed-Fi Tracker


The Ed-Fi Alliance tracks issues and feature requests in a tool called Tracker, available at http://tracker.ed-fi.org

...

. This allows the Ed-Fi Community to:

  • Search for an view existing ideas
  • View work in progress
  • Vote on issues
  • Add and comment on issues
  • View code commits and pull requests related to issues

To get started with Tracker, you need a login: you can get one by going to the Access Request Form. (This login is actually an SSO login that covers most

...

Ed-Fi online services).

Below are a few helpful outlines on common tasks with Ed-Fi Tracker tickets.

...

Submit an Issue

...


This section provides a walk through of submitting an issue to the Alliance. Note that the Data Standard issues are

...

publicly viewable, but you must login to submit tickets.

  1. Go to https://tracker.ed-fi.org and login.

  2. Click the "Create" button. 

...


  1. Image Added

  2. Select the Project and Issue Type. Data model tickets are placed in the Data Standard project

...

  1. and prefixed with "DATASTD-" in their ticket number.

...


  1. Image Added

    We ask that you use the following issue types (the other types are for internal usage).

    • Bug - Bugs/defects you have found on the code

...

    • Improvement - Suggested improvement or refactoring of the code for existing functionality

...


    • Question - Request for how to information or

...

    • ask a question on best practice
    • New Feature - New features with supporting use case

...



  1. Enter following information:

    • Summary. A brief description of the issue.
    • Fix Version/s. The specific version, if any, affected by the issue.
    • Issue Description. Be detailed. Below we include some Sample Tickets that can provide a guideline.
      • For bugs, please include the steps to reproduce the bug.
      • For

...

      • questions, please include use case details.
      • For improvements or new feature requests, please

...

    • Attachments. Attach any screen shots and/or code that can add clarity to the issue.

...

titleNew Feature Requests User Story

New Feature Requests User Story

Writing a User Story

When submitting a feature request, it is standard practice in Agile development to do so in the form of a "user story." A user story is a simple account of a feature told from the perspective of a user that is designed to ensure that requests are communicated with the baseline data needed for a developer and others to quickly understand the feature and why it is needed. A user story look like this:

As a {type of user},

I want {goal}

because {reason}.

The parts of a user story:

  • {type of user} - Identify who the specific user type is, as in "As a classroom teacher..." or "As the system database administrator...". A not so good example would be "As a user of the software...". If there is a characteristic that is critical to understanding this user, include that too: "As a classroom teacher who is using this software for the first time...".
  • {goal} - Say what the user is trying to do or accomplish. Try to describe the interaction as an outcome or goal, and resist describing it as a series of steps. "As a classroom teacher, I want to download the assessment results in text file format...".
  • {reason} - Say why the user wants to accomplish the goal

A full example would be:

As a classroom teacher,

I want to download the assessment results in text file format

because I may not have Excel or other required software applications installed on my computer.

Entering User Stories in Tracker

When submitting a feature request in Tracker, put the whole user story in the "Description" field.  A user story is designed to be a short but effective vehicle for communicating a need at a glance so others can see what is wanted, who needs it, and why. This allows it to be understood, sorted, voted on, etc. very quickly.

Also add any additional details you feel are important, or make suggestions as to the best way to supply this feature. Given the user story above, you might write: "Many teachers are using Google Docs instead of Microsoft Office, so when files are downloaded in Excel format they have trouble opening them" or "I think a drop-down offering an Excel and Text file options in the left corner would be best."

Finally, one best practice we recommend is to add to the description what is called "acceptance criteria." Acceptance criteria are suggestions designed to let the software developer know when the story is complete. To continue the example above, what if the teacher is able to download the assessment results, but her computer does not recognize the file as a text file? An acceptance criteria to fix this might look like this: 

When the file is downloaded, please ensure that it is recognized by the system as a text file and opens in the right application (e.g,. put a ".txt" on it, etc), including on my iPad.

This gives the developer who handles this story a list of specific item to test to ensure the story was completed successfully.

Info

You may also want to use visual panels to communicate related information, tips, or things users need to be aware of.

Track an Issue


The Ed-Fi Tracker allows for users to easily follow tickets and receive email updates when new comments are posted, changes to the ticket are made, or the status is updated.

  1. To track an issue, go to http://tracker.ed-fi.org and log in if you are not already.

  2. You can search for a ticket using the search at the top right of the page or with the filter.

  3. To expand the filter options, click View all issues and filters.

    Image Added
  4. Once you have selected the ticket you wish to track, click the Start watching this issue hyperlink.

    Image Added

    The number to the left shows how many people are currently watching this issue.

  5. As updates occur to the ticket, you will receive an email alert with a link to the ticket.

  6. To stop tracking a ticket, click the Stop watching this issue hyperlink.

    Image Added

Vote or Comment on an Issue


Often others have similar issues to yours and tickets on those issues already exist. It is a good idea, therefore, to search for existing issues and add your comments to those tickets where possible. Commenting or voting for an issue is the best way to ensure the Ed-Fi community has as much information as possible, all in the same place.

  1. To vote or comment on an issue, go to http://tracker.ed-fi.org and log in if you are not already.

  2. You can search for a ticket using the search at the top right of the page or with the filter.

  3. To expand the filter options, click View all issues and filters.

    Image Added

  4. Once you have selected the ticket, you can vote by clicking the Vote for this issue hyperlink on the right side of the page.

    Image Added

  5. And you can comment by scrolling down to the Comments section.

    Image Added

  6. Click the Comment button and include information like additional use cases or questions.

    Image Added

Data Standard Ticket Workflow


The life of a DATASTD ticket has many phases. To help understand the process, below is the overall workflow for the DATASTD tracker project followed by a few common paths DATASTD tickets take.

Image Modified

OPEN

All DATASTD tracker tickets are created with the OPEN status. In this phase, the a reporter can expect from the community additional information gathering, suggested best practices or workarounds, background information, and/or clarifications, depending on the nature of the ticket. If there are related tickets, they may be linked and the community can vote on tickets they'd like to see gain more visibility. 

UNDER ANALYSIS

Periodically the Alliance and other community groups will review suggestions for changes to the data standard. When a ticket has been selected for this process, it is moved from OPEN to UNDER ANALYSIS. These can include recommendations for new features and fixes to the existing data model and are most often grouped by the data domain (e.g. Student Enrollment, Assessment). While tickets are in this phase, contributors may add notes and comments or ask additional questions of the community in preparation of the discussion. During analysis, additional notes and recommendations for next steps will be notated in the comments as well. 

PLANNED FOR DEVELOPMENT

Tickets that have been approved for development during the UNDER ANALYSIS phase move here. Detailed steps on what is to be implemented along with a Data Standard Version are required. It is important to note while there is a plan to develop tickets in this phase, it is not a guarantee the changes will become part of a future release. Often times during development additional requirements or unforeseen complications can arise and more information may be necessary or additional steps taken before a ticket can move forward. When this is the case, the ticket will revert to UNDER ANALYSIS. Otherwise, the ticket will move on to IN DEVELOPMENT.

IN DEVELOPMENT/READY FOR REVIEW

Tickets that are actively being developed fall into this phase. Changes are made to the model and data standard artifacts are completed and for a final review before merging those changes into a corresponding development branch. As with the previous phases, during this stage complications may arise that require changes or a hold to the development process. If this is the case, the ticket may revert back to PLANNED FOR DEVELOPMENT as adjustments to the implementation plan are made. Otherwise, the ticket will move on to SCHEDULED FOR RELEASE.

SCHEDULED FOR RELEASE

After the changes designated by a ticket are implemented and merged into the corresponding development branch in GitHub, a release is assigned to the ticket and it moves to this final phase before CLOSED.

CLOSED

There are two main ways that a ticket will end up CLOSED. The first are OPEN tickets that are resolved without requiring any further discussion or changes to the data standard. The second are tickets SCHEDULED FOR RELEASE after the release occurs. At his stage, there no further action taken on the ticket.

Sample

...

Tickets 


Question

Info

Summary: How to record credits for multi-part course

Issue Type: Question

Fix Version/s: v3.0

Description:

As a school administrator, I want to know the best way to record a student's credits to the course transcript for a course that has multiple parts.

I would like to know how to properly record data around courses with multiple parts and student credits. Specifically, I need to address the following use cases:

  • Use Case 1 - A student was enrolled in a course with two parts offered in the Fall and Spring, passed both semesters, and earned credits for both course parts.
  • Use Case 2 - A student was enrolled in a course with two parts offered in the Fall and Spring, failed the first semester and passed the second semester, and earned credits for both course parts.
  • Use Case 3 - A student was enrolled in a course with two parts offered in the Fall and Spring, failed the first semester and passed the second semester, and earned credits for ONLY the second course part.
  • Use Case 4 - A student was enrolled in a course with two parts offered in the Fall and Spring, failed both semesters, and did not earn any credits.

Reporting a Bug

Info

Summary: StudentProgramAttendanceEvent can have records without a corresponding StudentProgramAssociation

...

Issue Type: Bug

Fix Version/s: v2.0, v2.2, v3.0, v3.1

Description: It has come to our attention that because the StudentProgramAttendanceEvent has separate references for Student, Program, and EducationOrganization, that an attendance event record can be created without the student having a StudentProgramAssociation record. Unless there is a use case where this would be necessary, we would recommend replacing the three separate references with a single StudentProgramAssociation reference instead.

New Feature Request

Info

Summary: Add enrollment type to StudentSchoolAssociation

Issue Type: New Feature

Fix Version/s: v3.1

Description:

As a SIS vendor, I would like to request an Enrollment/Membership type on the StudentSchoolAssociation to accommodate state implementation requirements.

A handful of state implementations record additional information on student enrollment/membership beyond knowing which school is the PrimarySchool for the student. We come across this need repeatedly in the field and would like to standardize how and where the information is recorded. Adding a EnrollmentTypeDescriptor with the most commonly recorded values as part of Ed-Fi core would remove the need for extensions across multiple implementations and provide the flexibility to add custom descriptor values.