Contributions

Last updated 5 months ago

This guide will help technical leadership and staff understand how contributions to the Elentra Platform can be made by your institution.

Contributions

The Elentra Consortium community consists of a vibrant and capable group of technical professionals, faculty members, and administrators from institutions all over the world. The success and size of the Elentra Platform is largely attributed to the valuable contributions by many of our Consortium Participant institutions.

This documentation is intended to describe the process that Consortium Participants should follow in order to have features or changes considered for contribution to the core platform.

If these procedures are followed, there stands a much better chance of the feature/change being merged into an upcoming release of the software and will also help to avoid unnecessary development efforts by your institution.

Communication

Before you begin detailed planning or development of a feature or change within the Elentra Platform, it is critical to communicate that change requirement to the rest of the community.

This communication step is of key importance because you or your team may gain valuable insight, knowledge, or feedback from an existing contributor.

Here are a few potential outcomes of first communicating the feature/change you are planning to make:

  1. It may already be possible to achieve in the application or may exist within a feature branch.

  2. There may be an existing Jira Issue that explains this feature or you may be able to contribute your requirements to an existing Issue.

  3. It may have been previously discussed in the community and a workaround or alternative approach might have been accepted.

  4. It may be entirely out-of-scope for the project.

  5. You may be onto something new and exciting! Wahoo!

Communication Methods

This list is intentionally not ordered given that different features or changes may require different approaches. Please use your best judgment.

  • Post a message in the #help channel within the Elentra Consortium Slack team for a quick sanity check. If you do not receive an acceptable response, then send an email explaining the feature or change to the developer-l@elentra.org mailing list.

  • At one of the bi-weekly Consortium Community web-conferences, you should mention the required features or changes during the "Community Contributions" segment.

  • You could discuss your feature or change requirements at one of our weekly School + Elentra Consortium Core check-in meetings.

Planning

You should consult with the Elentra Consortium Core team during the feature/change planning process. We may be able to provide valuable feedback or advice on items such as feature location, UI workflow, database design, permissions configuration, and more. The Elentra Consortium Core team is here to support you during your development process. You have free access to experts, including UI/UX designers and subject matter experts.

Jira Issue

It is essential that when you are creating a new feature or change within Elentra that you create a corresponding Issue within the corresponding Elentra Consortium Jira Project.

This Jira Issue (i.e. epic, story, task, or bug) number:

  1. will act as a reference when you are speaking with other Consortium Participants.

  2. is required to create a new database migration using php elentra migrate --create.

  3. will be used as a prefix in your feature or hotfix branch within our Git repository.

See more detail about creating Jira issues here.

Development

Institutional Fork

Development relating to your new feature or change will happen within your Institutional Fork of the ElentraProject/elentra-1x-me Git repository. This fork will give your team a place to perform active development of features without requiring write access to the main project repository.

Please pay special attention to ensuring that your Institutional Fork is kept up-to-date with the upstream ElentraProject/elentra-1x-me repository. GitHub, unfortunately, does not automatically maintain upstream commits in downstream forks.

Branching

Before development begins, you should create a new feature or hotfix branch based on our develop branch (or the release on which your installation is based).

Your feature branch should be named using the following naming convention, which can be broken down into three parts:

[feature|hotfix] / [UPPERCASE Jira Issue Number] - [lowercase Short Descriptive Label]

  1. Lowercase: The prefix indicating this is either a feature or hotfix branch. See Overview / Git Repositories for clarification.

  2. Uppercase: The corresponding Jira Issue number.

  3. Lowercase: A short descriptive label or slug for your feature or hotfix, concatenated with dashes.

Examples of correctly formatted branch names:

  • feature/ME-555-save-users-curriculum-track

  • hotfix/ME-741-fill-in-the-blank-exam-questions

Examples of incorrectly formatted branch names:

  • save-users-curriculum-track

  • feature/Save-Users-Curriculum-Track

  • feature/save-users-curriculum-track-555

  • bug/me-741-fill-in-the-blank-exam-questions

Coding

A few notes regarding development activity for the Elentra Platform:

  1. Updates to the existing Elentra ME codebase that are submitted for consideration should be in-line with the Elentra Coding Standards. Doing so will significantly expedite the code review process.

  2. New modules created for Elentra ME should be built using the Service Oriented Architecture pattern introduced in Elentra ME 1.10. This pattern consists of a RESTful Elentra API end-point created within a separate ElentraProject/elentra-1x-api repository, and a front-end created using Elentra JS (our implementation of VueJS). For more information on how this can be achieved, please refer to the Quickstart Guide or contact the Elentra Consortium Core team.

Submitting Contributions

Once the development of your feature/change is complete and you are ready to submit your work for consideration in the core code base, you must create a pull request on GitHub to our developbranch. The only exception to this rule is if you're submitting a bug fix for a previous version of Elentra. In that case, you would base your work off the specific release branch (i.e. release/1.12), and create a pull request back into that branch.

A pull request (shown below) should in most cases have a base of develop and compare to your feature/ME-2254-student-report branch. A few other very important notes about your pull request:

  1. It must have the Jira Issue Number as a prefix in the Pull Request title

  2. It must have an accurate and descriptive Title.

  3. It must contain a relatively informative description that includes a reference to the corresponding Jira Issue number (i.e https://elentra.atlassian.net/browse/ME-2254).

  4. You must notify us of the contribution so that we can tag with request as ready-for-code-review and indicate a preferred Milestone that this feature should be included with.

Once your pull request has been submitted you must inform the Elentra Consortium Core team and advocate for your feature.

It is important to note that pull requests are not always reviewed quickly. It may take many months for a pull request to be reviewed depending on its' size, priority, and backlog of requests. During this period it is your responsibility to keep the pull request relevant and up-to-date. We recommend that you routinely merge the develop branch into your feature branch to keep it up-to-date. A stale pull request containing many merge conflicts may not be reviewed.

Code Review

During the code review process, our Elentra Consortium Core team is assessing a number criteria including:

  • Security

  • Design

  • Functionality

  • Applicability

  • Flexibility

  • Coding Standards

  • Documentation

If we find minor issues, we will certainly fix them. If we find major issues, we may mark the pull request as requires-attention and provide feedback as to what is needed to proceed. We are here to help and happy to work with you, please do not hesitate to reach out for assistance.