4.1.1 Development Conventions
Oscar Code design and architecture is overseen by a technical committee. This is a high level developer group whose responsibilities include further codifying Oscar's development conventions to make it easier for high quality code to predictably be delivered on an ongoing schedule. What actually gets coded is intentionally free and open.
The idea is to provide tools to make it easier to leverage the code base and interface with group(s) that have an urgent need for a quick feature, while maintaining ISO standards and stability of the core, and of course open-source nature of the project.
Representation on this committee reflects the diverse backgrounds that Oscar developers have including McMaster, CAISI and independent developers, however if you have code committing privileges and feel that Oscar would benefit from your involvement on this working group please apply to Dr Chan.
Reporting includes the devel list serv and this, the Developers section of the new oscarmanual site.
Oscar has gone through a number of version numbering systems. Currently Oscar uses the convention that the first part of the version reflects the year of the release and the second part reflects a minor version. eg 10.12 refers to Oscar released at the (end) of December, 2010. Binary packages are numbered according to the following convention [epoch:]version[-revision]. Epoch is reserved for future use.
oscar-mcmaster_12-1.6.final.deb is Version 12 revision 1.6 (the final or stable release)
Any new feature that is being developed needs an accepted "Oscar Change Request" form and filed at Sourceforge as a "Feature Request" with the current template filled out. Please note that this differs from the wishlist. One will only place features into a Oscar Change request when one has secured resources and/or funding for the development.
Items from the wishlist (Recent notable examples of Rx3 and the Inbox) get occasionally incorporated into the code even without funding, on an irregular schedule.
Like other programs there is a sequence of testing that occurs. White box testing is done as the programmer codes to ensure that possible inputs are exercised through the code to determine the appropriate
outputs. The CVS itself is monitored by automated builds triggered by commits pushed upstream to Gerrit.
When new code builds without failure (programmatic and automated check style failures) it will be reviewed by humans to ensure that the code meets general coding standards at Oscar and does not conflict with higher level design considerations. The code then gets merged into the main branch (trunk) and/or named branches (New code can only go to trunk and branches tagged "updatable"). After the trunk is feature complete for a given branch it undergoes further testing and is branched.
Black Box or Feature testing as well as Alpha testing is done by clinics closely integrated with the development teams on trunk (the main branch). Beta testing occurs by technologically advanced early adopters after a named milestone release of new features.
Versions get released as milestone releases which contain new functionality but may be indistinguishable from the 'half hourly build' on the time of the release. These have only been alpha tested by clinics closely related to the development teams with production data, but not necessarily in production. At release no more features or database changes are allowed to the branch unless they are bug fixes.
From a production perspective when there is a branch, for Oscar it is as unstable as the trunk the day it buds (perhaps even more than usual as everyone has just committed code to make the deadline). You have to give it a little while for the bugs to come out minor nuisance - such as missing tags, or as serious as purple screens of death (PSOD ™ trademarked on behalf of Oscar) when you try a feature.
Its only once the code has stabilized by the programmers after beta testing by early adopters that it is suitable for installation for non technologically inclined users. In the past this has usually taken a month or so for the code base to settle.
For compliance releases (eg 9.06, 11.x and 12) the release cycle follows a more conventional pattern with the alpha and beta testing occurs before the branch is released on trunk. Thus for these releases the code base is already settled upon release.
Pre-packaged binary releases are released at various times, typically at least twice, one for an early beta and a second bug fix release when the code is considered stable. The second release is labelled final although further minor bug fixes may have occured and are available only in source code.
We use Git/Gerrit for versioning and vetting releases. All submitted code must be released under the GPL in current use by Oscar. Developer status with commit privileges can be extended to (or withdrawn from) individuals by the lead developer in charge of the project on an arbitrary basis. Currently the way to get privileges to commit is to apply for a user-name in Gerrit, as documented in IDE install. Commits should be labelled with the ID of the bug or Feature Request that reflects the OSCAR Change request or bug that is being addressed.
Coding style is documented in the docs directory of the source. Oscar observes a number of automated tests to see if the coding style is being conformed to and that the number of artifacts that are no longer supported decreases with time. A failed build through Gerrit usually means that one or more of the conventions has not been followed.
Our bug tracking system is on Sourceforge http://sourceforge.net/tracker/?group_id=66701&atid=515432
All and sundry are invited/encouraged to list bugs as they can't be squashed if we are unaware of them.
Browse the list of bugs to ensure that yours is a new one.
As always for best effect be sure to supply information so that it can be reproduced
- Version/Environment (eg Oscar 10.12 of July 19, 2011 on Ubuntu 10.4 Tomcat 6 MySQL 5 Sun Java 1.6)
- How you got to the bug (eg every time I click on the Inbox ....)
Screen shot if relevant (eg of missing or malformed labels)
And if possible an excerpt from the Catalina.out logfile found for the default Ubuntu 10.4 Oscar install at /var/lib/tomcat6/logs/catalina.out