- This line was added.
- This line was removed.
- Formatting was changed.
The Ed-Fi Alliance relies on technical contractors for a variety of critical projects and functions. This documentation provides guidelines that every technical resource is expected to know.
The Tao of the Ed-Fi Alliance
Every technical contractor is expected to have read The Tao of the Ed-Fi Alliance, which provides an overview of the organization, its mission, and the principles that drive its work. The Code of Conduct applies to everyone working with the Ed-Fi Alliance – but technical contractors have a particular responsibility to exemplify the conduct the Alliance expects from its community.
Resources and Access
Although the particulars are different based on a person's role, technical contractors are generally provided with access to the Ed-Fi Tracker / JIRA system, the Tech Docs / Confluence site, and GitHub repositories.
The Ed-Fi Developer Guide has a good overview of the resources available. Technical contractors can work with their internal project manager or Ed-Fi technical lead to be granted appropriate access.
Information Security and Privacy
The Ed-Fi Alliance expects every technical contractor to consider data security and student privacy at every stage of their work.
Some specific practices of note:
- Use sample data. The Alliance provides sample and synthesized data sets for development work. Generally speaking, internal projects of the Alliance should never use real or production data containing any personally identifying information.
- Secure by default. When designing and developing systems for the Ed-Fi Alliance, use coding patterns that are secure by default. Force secure connections for hosted systems.
- Delete data after use, even if it's de-identified. In the course of Alliance work, you may be exposed to de-identified production data. Even though the information masks personally identifying information it should still be treated as sensitive – so delete it as soon as the task at hand is complete.
The above isn't meant to be an exhaustive list, of course. Check with your technology lead or Ed-Fi contact if you see any real or potential risks to security or privacy.
Ed-Fi Tracker / JIRA Ticket Guidelines
General Tracker Guidelines
Tracker tickets must communicate clearly. This is true of all Alliance projects, but especially important on public-facing projects where a Tracker entry may be the only source of information about a planned feature or a critical bug.
Every project has its own particulars, but a few rules apply to all projects:
- The ticket subject should summarize clearly the proposed feature, problem, or change.
- Avoid ticket subjects like "Improve the login process," "Make interface changes," or "Code library needs update." 1
- If the ticket is for an externally focused entity, clarify the audience or use case.
- Example: "Add a 'RequiredTechnology' or similar field to Section entity to support use cases involving virtual schools."
- The ticket description should provide detail about the proposed feature, problem, or change.
- Describe the change required in detail.
- Say why the change is needed. What problem does it solve?
- For bug reports, list environmental details (e.g., code versions, technology stack, environment).
- List acceptance criteria if those are appropriate and available.
- If you had to ask a QA person to test this change, what would that person do? The ticket should contain pointers to related code areas or affected functionality.
Internal-Facing vs. External-Facing Tracker Projects
There is a difference between external, community-facing projects and internal projects:
- External projects are those projects available to all licensees or those we expect to publish to all licensees in an upcoming release.
- The main external projects include: General Ed-Fi Alliance Tracker (EDFI); Ed-Fi Data Standard (DATASTD); Ed-Fi ODS / API (ODS); and Ed-Fi Dashboards (DASH), though there are several others.
- Internal projects include: Dashboard ETL project (ETL); Ed-Fi Data Standard Modeling (MODL); various vendor-specific work tracking such as DLP, TAHS, TAPLACID (logins required); and various internal development projects like METAED and MAPEDU (logins required).
- Projects may move from internal to external mode, often following a release.
In external-facing projects, some additional considerations apply:
- Tickets should be written so that they supply context and information such that an external party can understand the issue.
- This means avoiding references to local projects without supplying enough information on those projects so that they can be understood.
- Wherever possible, cite use cases that can be understood by the community and not just the team.
- Bug tickets should be written assuming that they will be shared as an early “public warning”.
- It is especially important that ticket summaries make it clear if a field implementation would be affected, and that descriptions supply missing details to help field implementations assess if they are affected.
- Clearly describe the risks. Be specific. Don’t overgeneralize.
- List any known workarounds.
- Assume a “friendly warning” tone for the community. The ticket should address the potential Ed-Fi community of users, while focusing on the specific technical issue.
- It's okay to rewrite ticket titles and descriptions as new information comes in.
Technical Community Contracting Outside the Alliance
Most Ed-Fi Alliance technical contractors also do work for the Ed-Fi Community.
- Technical contractors' work and contracts with the community are theirs and theirs alone!
- Internal or not-yet-released technology artifacts or other intellectual property produced for the Alliance should not be provided or used in outside projects.
- It's okay, of course, to engage in initial, conceptual discussions about leveraging in-progress technology without consulting the Alliance.
- However, you should reach out to a technical manager at the Alliance when making a formal proposal or bid response to ensure you're not proposing something to which the Alliance will object. The Alliance will treat any discussions as confidential. If you do not feel comfortable communicating with the Alliance that's fine – but caveat your proposal accordingly.
- The Alliance is happy to consider how to assist those projects, but we need to make sure that there is a level playing field for all Ed-Fi technology vendor organizations.
- Community engagement is critical to the Ed-Fi mission.
- We encourage all community members and contractors to report bugs, provide feedback, and raise tickets when technology decisions or code changes deviate from the core Ed-Fi technology stack, particularly when those deviations threaten the Ed-Fi interoperability mission. We expect technical contractors to be model citizens in that respect.
- We encourage technical contractors to involve community members in technical feedback, for example, by submitting Tracker tickets and attending technical meetings. These actions make the community stronger.
1 Some teams use Tracker for long-term estimation and planning, and in those cases it's okay to have general ticket names. However, the ticket is expected to evolve into something specific and detailed as actual work gets underway.