Contributions

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.

High level diagram of the code contribution workflow

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 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 from your Institutional Fork into the appropriate branch within the Consortium Edition repository.

Generally speaking, a new feature pull request should have a base branch of develop and compare to your feature branch (e.g., feature/ME-1234-student-report). A bug fix pull request should have a release branch base (e.g., release/1.15) and compare to your hotfix branch (e.g., hotfox/ME-1235-student-bug-fix).

A few other very important notes when submitting a pull request.

In GitHub

1. The Pull Request Title must have the Jira Issue Number as a prefix.

2. The Pull Request Title must be accurate and descriptive.

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).

Example of well formed GitHub Pull Request for ME-2296.

In Jira

1. The Jira Issue Number must exist.

2. The Jira Issue must have a blank Assignee field.

3. The Jira Issue must have a Status field set to "In Review".

Jira Issues must be set to In Review with no Assignee.

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

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.