Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

Updated: September 29th, 2019

The Ed-Fi Alliance welcomes code contributions from the community. This documentation provides guidelines for making contributions. Although the details and examples that follow are focused on the Ed-Fi ODS / API, the same principles and requirements are applicable to most Ed-Fi Alliance products.

In general, contributions will be released with next scheduled release of the ODS / API.  Exceptions include cases where contributions introduce breaking data standard changes or ODS / API behaviors (in which case they are rolled into the next major version release) and cases where a timely change is needed for the current release (in which case the Ed-Fi Alliance will create a new hotfix/minor release with the appropriate change incorporated).

In order to contribute code, please follow these guidelines: 

  1. Create an Ed-Fi Tracker ticket describing the feature/bug/change. Once a discussion of the feature and/or fix is confirmed within the ticket, it is ready to be worked on. 
  2. Create a fork in GitHub.
  3. Create a branch off of active development branch for the Technical Suite. By convention, the Alliance uses the JIRA Issue ID followed by the Technical Suite number (e.g., ODS-3140-v3). 
  4. Commit your changes and push your changes to GitHub. Keep commits granular and specific. Multiple small commits are favored over a large commit. Do not include ticket numbers in the commit messages.
  5. Create a pull request against the origin's development branch for the technical suite. To ensure proper GitHub links in JIRA, pull requests should have the ticket numbers in brackets at the beginning of the title. The title should be a simple version of the addition, change, or fix. This is often similar to the title of the ticket (e.g., "[ODS-3140] PostgreSQL support for Identity Value Mappers").

An Ed-Fi core team member will review your pull request for the following requirements:

  1. The pull request has Ed-Fi Tracker ticket.
  2. The changes in the pull request follow the coding standards as documented by C# Coding Standards.
  3. The pull request meets the acceptance criteria as defined in the Ed-Fi Tracker ticket.
  4. The pull request includes appropriate unit test coverage and/or integration test coverage. Postman tests may be required when a feature or fix directly effects the API behavior. For now, these tests can be as simple as providing sample JSON for the test case (i.e., post JSON with an expected response JSON) and/or a collection that can be run attached to the ticket.
    • The Ed-Fi Alliance is working on a Postman test script suite in the Ed-Fi-ODS\Postman folder of the code base. When complete, we will incorporate your tests into it.
  5. The pull request changes should be re-based onto the corresponding active development branch for the technical suite. For example, if the fix or feature is for Technical Suite Three, then those changes need to be rebased onto the end of development-v3 branch. The blog post Git rebase: reapply your changes onto another branch is an informative guide to what it means to rebase within Git.
  6. The revised code must pass all existing and new tests. Some tests take long time to run. The reviewer can run these tests on Ed-Fi build server and provide feedback if the tests have passed or failed.

Multiple Repositories

In the case where changes for a ticket span multiple Git repositories, the pull request will be merged into a feature branch first for testing and validation. The reviewer will create a feature branch based on the active development branch and then change the target of the pull request to point to the feature branch. The reviewer then will merge the code, keeping the commits in the feature branch until after review comments have been satisfied and functional and unit tests are passing. 

Once the above criteria are met, a final pull request will be submitted to move the changes into the development branch by the reviewer where the multiple commits will be squashed into a single commit.

Git Tools

A list of Git GUI Clients are posted on the main Git site. Some commonly used GUI clients by the ODS development team include: Source Tree, Git Extensions and Git Kraken. For diffs and merges the team primarily uses KDiff3. However, there are other tools available, including Meld, Diff Merge, and Beyond Compare.

The following command will setup KDiff3 as your default GUI for merges and diffs:

git config --global --add merge.tool kdiff3
git config --global --add mergetool.kdiff3.path "C:/Program Files/KDiff3/kdiff3.exe"
git config --global --add mergetool.kdiff3.trustExitCode false

git config --global --add diff.guitool kdiff3
git config --global --add difftool.kdiff3.path "C:/Program Files/KDiff3/kdiff3.exe"
git config --global --add difftool.kdiff3.trustExitCode false

Further reading on Git can be found on the docs site.

A Note on Acceptance

To help the requester meet the acceptance criteria, changes may be required. These changes may include support for consistency of unpublished changes and/or to support the architecture of the application. 


  • No labels