This guide will help technical leadership and staff understand how contributions to the Elentra Platform can be made by your institution.
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.
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.
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:
It may already be possible to achieve in the application or may exist within a feature branch.
There may be an existing Jira Issue that explains this feature or you may be able to contribute your requirements to an existing Issue.
It may have been previously discussed in the community and a workaround or alternative approach might have been accepted.
It may be entirely out-of-scope for the project.
You may be onto something new and exciting! Wahoo!
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 firstname.lastname@example.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.
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.
This Jira Issue (i.e. epic, story, task, or bug) number:
will act as a reference when you are speaking with other Consortium Participants.
is required to create a new database migration using
php elentra migrate --create.
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 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.
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]
Lowercase: The prefix indicating this is either a
hotfix branch. See Overview / Git Repositories for clarification.
Uppercase: The corresponding Jira Issue number.
Lowercase: A short descriptive label or slug for your feature or hotfix, concatenated with dashes.
Examples of correctly formatted branch names:
Examples of incorrectly formatted branch names:
A few notes regarding development activity for the Elentra Platform:
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.
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.
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:
It must have the Jira Issue Number as a prefix in the Pull Request title
It must have an accurate and descriptive Title.
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).
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.
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.
During the code review process, our Elentra Consortium Core team is assessing a number criteria including:
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.