Page Comparison

The Ed-Fi Alliance welcomes code contributions from the community. 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

1. an Ed-Fi Tracker

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

1. 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). 
2. Commit your changes and push your changes to GitHub

1. . Keep commits granular and specific. Multiple small commits are favored over a large commit. Do not include ticket numbers in the commit messages.
2. Create a pull request against the origin'

DOs and DON'Ts

• DO follow our coding style (see below).
• DO include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
• DO keep the discussions focused. When a new or related topic comes up, it's often better to create a new issue than to sidetrack the discussion.
• DON'T surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time.

Issues

If an issue is complex, consider filing it and giving us time to respond before sending a corresponding Pull Request. If you want to work on the issue, just let it be known on the issue thread. Giving us a chance to review the issue may save considerable time. For example, we might let you know why existing behavior can't be changed or about particular implementation constraints you need to keep in mind, and so forth.

Don't feel obliged to match every issue with a Pull Request. Simply filing issues for problems you encounter is a great way to contribute, too.

Licensing

• DON'T submit Pull Requests that alter licensing-related files or headers. If you believe there's a problem with them, file an issue and let us take care of it.

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