OSCAR Development Notes
This page is to document how the SCOOP local repo OSCAR should be accessed/handled.
The main intention for this repo's existence is to provide the SCOOP team with a repository to upload progressive commits to creating the feature "Patient Demographic Export for Other Provinces - ID: 3563797". We intend to have a branch within this repo with our changes, and frequently update from the official OSCAR repo to keep things up to date. To this end, the following are instructions on how to set up your local repo to contribute. We intend to return our development efforts in one week sprints back to the community through OSCAR's gerrit system.
git clone [email protected]:scoophealth/oscar.git
cd oscar
You now have a copy of the OSCAR repo. However, we want to also be in sync with the official OSCAR repo and not only with this copy, so we need to define the upstream source.
git remote add upstream ssh://<user>@source.oscartools.org:29418/oscar
Note that you need to replace user with your username on Gerrit. Then to check if it's set up correctly, do
git remote -v show
And you should expect to see two things: origin pointing to [email protected]:scoophealth/oscar.git and upstream pointing to ssh://<user>@source.oscartools.org:29418/oscar.
Next, we need to streamline the update and pull process to keep things in sync.
vi .git/config
In the config file, add the following:
[alias]
pumaster = !"git checkout master;git fetch origin -v; git fetch upstream -v; git merge upstream/master"
pu121 = !"git checkout RELEASE_12_1;git fetch origin -v; git fetch upstream -v; git merge upstream/RELEASE_12_1"
gerritpushmaster = !"git push upstream HEAD:refs/for/master"
gerritpush121 = !"git push upstream HEAD:refs/for/master"
With this, you can now do git pumaster and it will fetch the origin, fetch the upstream, and merge the upstream updates to your local master branch. You can then do git push origin master to update our local repository on github with the new changes. git pu121 also does a similar thing, but updates our local RELEASE_12_1 branch with the upstream version. git gerritpushmaster allows you to submit your code changes up to OSCAR's gerrit master branch for code review and eventual inclusion into the main code.
Lastly, in order to stay synced with the gerrit code review, we need to make sure our local repository is hooked into the commit messages. To do this, we do the following:
scp -p -P 29418 <user>@source.oscartools.org:hooks/commit-msg .git/hooks/
Remember to replace user with your own username. These hooks will allow us to work with the code review process and ammend our commits as needed.
To build our feature, we will branch from master and commit our additions to the branch "scoop-dev". As we continue to add commits, we will frequently keep our local master and RELEASE_12_1 branches in sync with upstream, and attempt to keep our branch updated to the latest changes by rebasing our work on top of it.
git checkout master
git pumaster
git push origin master
git checkout scoop-dev
git pull --rebase origin master
This will let our changes appear as if they started on the most recent master change. Doing the rebase repeatedly however introduces some issues. Since we are rewriting history on our scoop-dev branch consistently, we will be forcing that branch on our github repo to be overwritten instead of merging on top of it (aka people won't be able to fast-forward with it anymore). Since this is prone to potential history corruption, this will be done in a controlled setting when all developers are on the same page.
Because Git is a decentralized source control system, multiple developers will inevitably trample on each other when submitting their code. In order to avoid that, we will do a best attempt effort to keep the commit history sequential and merge-free. To do this, before commiting your latest work, make sure you get the latest version of the repo from Github, update your branch, replay your new work on top, and then push. The general steps are listed below.
git add . (Stage all your planned new changes)
git stash (Save the changes to a stack and restore branch to last HEAD state)
git fetch (Retrieve any new commits remotely)
git merge origin/scoop-dev (Fast forward your head to latest commit)
git stash pop (Reapply your new changes to the branch and resolve any conflicts if any)
git add . (Re-add all your planned new changes)
git commit -m "Message" --signoff (Commit your change)
git push origin scoop-dev (Push your commit back to repo)
When we reach a point where we are ready to commit back to the upstream, we will squash all of our commits to one commit, rebase to the most recent master branch commit, run the appropriate tests, and push that upstream to submit our changes. The reason we do this is to take the brunt of the merge work. It is better that we resolve the merge conflicts ourselves instead of forcing others to resolve them.
The diagram above gives an idea of what we want to accomplish. Gerrit 1 represents the original main repository from gerrit where we pulled from originally. Github 1 is our local scoophealth repository where we will put our work at. As we create commits such as E and F, we will periodically merge via rebasing the new changes from master into the scoop-dev branch.
Once we are happy with the scoop-dev branch and are ready to commit back to gerrit upstream, we will squash all of the scoop-dev branch into one commit as shown on Github 2, and then we will merge that to the master branch on node H. What this will look like for Gerrit in Gerrit 2 is that we made a bunch of changes in one commit, and then merged them back into master. This way, we will be able to track all our development changes, and when we are done, submit the feature as one nice commit to the OSCAR community.
Below is a recent exerpt from the oscar-dev mailing list.
If you commit code to gerrit, and it fails the jenkins build. you MUST fix this if you want us to consider the change. If you are still on the git/gerrit learning curve, and you'd like to work with us to have your commit pass the build, and be "review ready", please ask on this list and reference the gerrit url OR email me directly, and I'd be happy to work with you offlist (you still have to do the work).
If you have no intention of amending the commit, and would like to pass it on to us to do as we would like to (either abandon, or have us take the time to make the commit mergeable, please let us know (preferably in the commit message), so things don't linger in the queue.
Remember to suffix commit messages with (DO NOT REVIEW) and/or -1 the commit yourself immediately after pushing if you don't want a review on that particular patchset.
Remember that new commits can be based on anything abandoned. So if we abandon, and you'd like to resubmit, check out the original commit, make changes, amend it, rebase it off a recently merged commit (check the dependency chain using git log), and push back under a new commit...that's no problem.
Reference your sourceforge ID in the commit message again. Best practice is
ID: - Feature -
ID: - Bug -
All of this will help make the process more efficient for submitters and reviewers.
thanks again for all your efforts and active participation.
Since contributing back to the OSCAR community goes through gerrit, we have to squash our commits together before submission. The act of squashing deletes our explicit commit history. In order to retain our local commit history with scoop-dev, we will make a copy of that branch and save that as a tag named something like scoop-2013w17. This allows us to retain our commit history if we need to go look it up again.
With scoop-2013w17, it means that the copy branch was generated on the 17th week of 2013. Creating this copy branch must be done before the squash; otherwise we will not retain the history. As an aside, branches and tags are essentially pointers to a specific commit. The only difference is that branches are mutable while tags are not. Since we are only retaining history and not actively adding to those commits anymore, we will be using tags to point to the historical commits.
In order to create a copy of the history, make sure you are currently on the scoop-dev branch. Then apply a tag to the current commit and push the tag up to the remote repository. An example is as follows:
git checkout scoop-dev
git tag -a "scoop-2013w17" -m "SCOOP E2E 2013 Week 17" (create the tag)
git push origin scoop-2013w17 (push the new tag to the remote repository)
Once the copy is generated, we can squash the scoop-dev branch to one commit, test, and submit back to the community. When that is done, we should expect the scoop-dev branch to be exactly 1 commit ahead of the master branch. That commit will be our squashed content. Below is an outline of the rebase squash process.
git rebase -i master (open the interactive rebaser)
At this point, you will get a file with a list of commits and picks. To transform all of them to a single commit, change the first commit as a edit (and edit the commit message later to have the SourceForge ID), and for all subsequent commits, replace the word pick with squash. For example:
pick fda59df commit 1
pick x536897 commit 2
pick c01a668 commit 3
Should become
edit fda59df commit 1
squash x536897 commit 2
squash c01a668 commit 3
Afterwards, save the file and git will perform the squash. As well, since we are pushing this up to gerrit, make sure you edit the commit message to follow the ID:xxx - Feature - style.
Since we are submitting to gerrit for code review, it is very likely that we may need to do some modifications to our submission. In order to allow for modifications to our submission as well as continue development on scoop-dev, what we will do is create a local-only temporary branch which contains our new squashed commit. This branch can be named anything, but its main purpose is to allow us to respond to the code review by amending it.
git branch 2013w17temp
Below is an example workflow of what we would need to do if we need to amend our submission. Since we are amending, we need to make sure our subsequent work also knows about the changes.
git checkout 2013w17temp (then edit your code as needed)
git add . (stage your changes)
git commit --amend (add your changes to the previously squashed commit)
git gerritpushmaster (send the updated squash back to gerrit)
At this point, we've successfully responded to the code review from gerrit. Now we have to make sure our subsequent scoop-dev work knows about the changes. We do this by rebasing our work on top of the new squash.
git checkout scoop-dev
git rebase -i 2013w17temp (open the interactive rebaser)
Once again, we're in the interactive rebaser. This time, since we only want to rebase onto the new squash, we want to copy everything on scoop-dev onto the new squash EXCEPT the old version of the squash. Figure out which one of the commits is the old squash version and comment that line out with a # at the beginning. If you forget to do that, the rebase will definitely fail and you'll have to revert back and try again.
Remember, when a commit is amended, its hash also changes. As well, during the interactive rebase, generally the old squash will be the last line, and assuming you've renamed the squash message to follow conventions, it will be very clear which commit it is (the message will be in the ID:xxx - Feature - format).
After the rebase, make sure you update our scoophealth repo with the updated scoop-dev branch. As with any history rewrite, if you aren't sure what you are doing, make sure you ask one of the lab members to help you.
git push origin scoop-dev --force (be careful with force overwriting as this is destructive if done incorrectly)
From this point onwards, you may continue development on scoop-dev, and address any code tweaks and changes requested from the community on the master branch.
Once our submission is accepted and merged into the master branch, we need to make sure we remove our temporary squashes and realign our new commits on the newly merged in submission.
git pumaster (pull the latest changes from master)
git push origin master (update our scoophealth repo with the changes)
git branch -D 2013w17temp (delete our temporary branch for squash amends)
git checkout scoop-dev (return to our dev branch)
git rebase -i master
Once again here, we are rewriting history; only this time, we are basing it off of master in its entirety instead of our pending submission. This is because the pending submission is now officially part of the OSCAR codebase, so we do not want to have a redundant commit in there. In the editor, just comment out the old squashed commit and let it rebase from there.
When that is done, make sure you once again update our scoop-dev branch to reflect the new changes.
git push origin scoop-dev --force (be careful with force overwriting as this is destructive if done incorrectly)
Below is the current design for the E2E Template Export feature. This diagram may change as development continues.
We will attempt to stay true to the MVC design. Velocity based templating requires both a template and a data model. We have the PatientExport object draw on all the pre-existing DAOs and models and have it group up the relevant fields for easy velocity access. Most of the heavy code work will be found in e2etemplate.vm, and DemographicExportAction4.java acts as the Event Handler and file management for the export function.
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
