Developer Workshop 2015 Marc Dumontier McMaster/OSCAR-EMR
Agenda Code Submission 101 Infrastructure Tools Developing OSCAR
Code Submission: Process OSCAR EMR Sourceforge http://www.sourceforge.net/projects/oscarmcmaster
Code Submission: New Feature Need to be logged into sourceforge. Create a new ticket under the feature requests tracker. You are presented with a template. Copy and paste the headers, and fill out every section. Attach relevant documents. Sections include change benefit, interaction points, integration risks, risk if not incorporated, minimum testing requirements, training requirements, time estimate. Set the proper milestone and priority What happens next?
Code Submission: bug reporting Sourceforge can be anonymous. Use the bug tracker. No standard template yet. Provide detailed steps to reproduce bug (how did I get to this page). Include stack trace if available (screen or catalina.out) Include additional supporting material where possible (de-identified lab). Be specific about the version you are running. Helpful to specify expected behaviour as well as the observed behaviour. Setting priorities. Are you sure it's a 9?
Code Submission: Following up As a developer, you should update the ticket when making a commit to cross link them. Commit message must include the Sourceforge ID Ticket comment should be added with Gerrit URL to commit Ticket should be updated to open-fixed if appropriate. After the code has been accepted and merged, you should verify the fix, and the ticket should be updated closed-fixed Many ways for features and bugs to progress through the quality management worflow (see OSCAR EMR diagrams)
Infrastructure GIT Gerrit Jenkins DEB packaging
GIT Source Code Management OSCAR EMR hosts GIT and mirrors it to Sourceforge. You can use the sourceforge one only as read-only. Branching stategy Commonly used commands: clone, checkout, pull, fetch, commit, push, status, log, diff Lesser used commands: rebase, cherry-pick
Git continued git clone (get a copy of the repository locally) git checkout (set the working index to a specific commit or HEAD. git pull (fetch latest from remote + update current branch) git fetch (get all the missing commits from remote. Doesn't affect working index) git commit (self explanatory) git status (tells you what's going on) git log (shows history up to the current commit
Branching
Git: Branching If you want your change in OSCAR 15. Commit to RELEASE_15_BETA and master If you want your change in OSCAR 15.1. Commit to master only If you fix a major bug, commit to RELEASE_12_1 (if appropriate), RELEASE_15_BETA (if appropriate), and master. Cherry-pick is useful here. QA team is useful here too.
Git continued git cherry-pick (takes the commit, and commits it to your local index. We use this to copy a commit to another branch) git rebase (rewrite history good way to move your commit to a new point on a branch, or to clean up depency chain you may have) example. You have a commit in gerrit, but master has changed before yours is merged in such a way that it cannot be merged. Checkout commit, git rebase -i origin/<branch>. Fix merge conflicts, git add <files>, git rebase continue, push.
GIT Resources http://git-scm.com/docs/user-manual.html documentation and oscar source from gerrit
Gerrit Gerrit is a web based code review system. Developed by Google for Android. Developers commit code to Gerrit Code review process initiated by a commit to Gerrit. Code Reviewers approve, and merge code to GIT Web based side by side view of changes (diff)
Gerrit: Setup https://source.oscartools.org:8080/
Gerrit: Setup You need a GitHub account for logging in. You need to set your preferred Email and username in your gerrit profile (as well as confirm the email). You need to upload an SSH key You need to request an admin add you to the code committer group.
Gerrit: committing Send code changes to a specific branch using the remote ref argument of git push git push ssh://hexbinary@source.oscartools.org:29418/oscar HEAD:refs/for/master You'll usually send code to refs/for/master refs/for/release_12_1 refs/for/release_15_beta If the build passes (more on this later), then a code reviewer will review, and either approve or give feedback on changes required for approval On approval, the code will be merged
Gerrit: committing Before you git commit Checking what files you will send using git status Checking what code you are sending using git diff Setting the commit msg as #<sf id> - <sf description>\n other stuff
Gerrit: Code Review Code reviewers will add comments while reviewing (code level and commit level) Voting system (+2,+1,0,-1,-2) Draft comments are not published to others! Make sure you reply to publish them.
Gerrit: Code Review Closing streams using finally clause Staying away from DBHandler Removing dependencies / rebasing Adding security checks Auditing PHI access DB Scripts Date / Time handling Using null instead of empty value
Gerrit: Code Review
Gerrit: Amending commits Commits often need to be amended Code change required to fix issue identified yourself or by review process Rebasing due to conflicts between the commit, and the branch it is attempted to be merged to If it's the last commit you did in your workspace, you can change the files, and then commit with amend as an argument to change the last commit instead of making a new one. You then need to push that back to your ORIGINAL commit as a new patchset
Gerrit: Common Issues I can't push, I get a permission denied error The commit includes files I didn't want to send No one is reviewing my commit Not including the sourceforge bug / feature change ID in the commit message Pushing to the stable branch, and not to master as well. Commits are too large Commits include code from other things being worked on
Jenkins Jenkins is a Continuous Integration (CI) server Every commit gets verified by jenkins by running maven Jenkins runs (mvn clean verify pmd:pmd) What gets checked Checkstyle (see rules in utils/checkstyle.xml) Compile Test (we have reflection based testing on DAOs) Licenses (see utils/headers, pom.xml) JSP compile PMD Console output
Jenkins
Sourceforge https://sourceforge.net/projects/oscarmcmaster/ File releases Mailing lists Bug and Feature Requests trackers Git browser DEB created by Peter HC as volunteer contributions
Developing: OSCAR JAVA based project Built using maven Runs on Tomcat MySQL support 15 year project with many different ways of doing the same thing..some good, some bad. Major workflows for having code get run Struts 1.x based Actions Directly from JSP as scriptlets Web services (SOAP and REST) Database is mostly not tightly constrained.
Important classes AbstractModel / AbstractDao MiscUtils SpringUtils
Developing: Environment Linux vs. Windows based environment Setting up multiple OSCARs on a single machine Using multiple workspaces Using different JAVA and Tomcat implementations on a single machine Building from the command line Eclipse is the most commonly used IDE for developing OSCAR.
Developing: Concerns Copyrights Checking for appropriate Roles/Rights using SecurityInfoManager LoggedInInfo contains user information. Available from session. Audit Logging important events Avoid direct SQL access (DBHandler, etc) Property files Preferences Write it as a service New UI
Developing: new UI Codename: cobalt Requires the REST module be loaded Angular based Bootstrap based REST services
Getting Help Sourceforge mailing list oscarmcmaster-devel OCUS OSCAR-EMR User groups