OSEE/Software Development Process
The OSEE team uses Agile methods to develop OSEE. While the Agile Manifesto values individuals and interactions over tools, we have identified elements of the Agile Process that can be enhanced by the concepts embodied in OSEE.
The OSEE development team understands and uses the Agile Development Process. The Agile process is continuous – the team has a Product Owner who understands the goals for the product and keeps a backlog of items. For the OSEE team, the most convenient way to understand what needs to be done to improve or fix OSEE is to use the tool to manage its own Actions. The Action provides enough information to determine what part of OSEE the Action applies to, who initiated the Action, and the exit criteria for completion of the Action.
Development of OSEE is divided into Sprints. The Product Owner reviews the backlog Actions, and provides a groomed list of Actions to the team to include in Sprint planning. The team chooses the most important Actions and assigns story points to each candidate Action. The story points provide a way to identify the level of effort required to complete an Action. The process emphasizes team interaction, and the team buys-in to all of the actions in the Sprint because they are involved in the selection of Actions. The selected Actions are given a Goal order to suggest the order they should be addressed. The Sprint typically starts the day after the previous Sprint is completed.
Sprint progress is monitored using daily Scrum meetings. During the meeting, each developer reports progress on the Actions they are working. Anything blocking the developer from completing an Action is raised in the Scrum meeting so help can be obtained. Completed Actions are marked, and developers are assigned remaining Actions from the Sprint plan. Project metrics are collected that show how many story points are completed. The OSEE team uses a combination burn down/burn up chart that shows how far along the plan the team is and how much completed work the team has accomplished.
At the end of the Sprint, a Sprint Retrospective is used to review with the team how well the Sprint went. The Retrospective covers what went well and what didn’t with an eye to improving future Sprints. Team Velocity, a measurement of the number of story points per day per person, is collected and graphed to show how the Sprint compares to other Sprints. The Sprint Planning process repeats and the next Sprint starts.
TODO: Add bugzilla relation to planning
The OSEE team utilizes its Action Tracking System (ATS) to capture and track OSEE software actions. OSEE users have the ability to submit change requests (e.g. bugzilla) describing something a user wants (e.g. a new feature or a software bug fix). These actions reside in an ordered backlog where they are evaluated and prioritized to be resolved, tested, and released appropriately using the agile software process. The OSEE product backlog consists of features, bugs, technical work, and knowledge acquisition items. Items in this backlog are sorted through a collaborative approach with users/stakeholders and planned for work.
TODO: Add reference links for bugzilla or other process references.
Requirements for OSEE are an on-going process. User Stories are drawn up for each key use case. Software requirements are derived from the User stories. The intent is to identify WHAT OSEE needs to do in order to fulfill customer acceptance for a particular use case. Requirements are meant to be high level and not focused on how OSEE will accomplish each task.
"OSEE shall access an outside system that maintains requirements" is WHAT it will do. "OSEE shall import requirements from DOORS" is HOW.
TODO: Add Functional decomposition information
- What open source libraries already provide part or all of the solution?
- Remove inclusion of unnecessarily specific restrictions (i.e. generalize the solution)
- Carefully consider consistency with and impact to overall system architecture
- Minimize the user support this feature will require.
- Consider use of appropriate software patterns.
- Consider the concurrency implications – including does the design take advantage of multiple cores
- Interface design considerations
- API compatibility - Binary vs. source vs. contract
- Gracefully handle bad data, invalid states, etc.
- Usability – work closely with customer on visual interface
TODO: Add link to software architecture/design TODO: How is the design documented? TODO: What process is used to design? TODO: How will the design impact Datastore/Data model compatibility? TODO: Trace design to requirements
Software Implementation Process
The phase in the software life-cyle where the actual software is implemented for the project. This process includes: updating production software, updating test software, verifying changes through unit tests and system level tests, committing changes into version control, making local builds and submitting changes for review.
TODO: Add Implementation Process Diagram TODO: Add customer review block as part of implementation cycle TODO: Add documentation TODO: Add Checklists and static analysis checks before submission
Tests accompany all new code created or modified. Tests can either be integration tests (end-to-end) functional testing or pure unit tests. For unit tests, JUnit and Mockito (http://code.google.com/p/mockito/) are used to quickly create test mock data types. Mockito mock types can be setup to return predetermined values which can be used in assert statements to test functionality. Tests are put into a fragment bundle where the host bundle contains the code being tested. The fragment will have the same name as the host bundle with “.test” appended to it. The package structure will mirror that of the host bundle (i.e. it will not contain ".test" in any package). The test class will have the same name as the unit under test with "Test" appended. Each test method in the test class will be named testMethodName() where methodName() is the method being tested in the unit under test. Each package will contain a package test suite file that lists which classes are run as a part of that test. Within Eclipse, the Emma code coverage tool can be used for unit tests. Unit tests should cover at least 80% of the new code.
TODO: Discuss test bundle structure and test suites TODO: Add test patterns such as: setup, exercise, verify TODO: Add client integration tests vs unit tests TODO: Client test framework - rules, monitorlog, etc.. TODO: Discuss how tests behave during build, what is accessible (accessing resources) TODO: Add Test philosophy? Large number of unit test vs functional/integration tests. TODO: Module tests vs full system level tests. TODO: Test speed
Reviews are done using the Gerrit Code Review tool. After code has been written, it is submitted to Gerrit which allows other developers a chance to review the code prior to it being merged into a baseline branch. Information on how to configure Git to use Gerrit can be found here: . Comments can be made in Gerrit in-line of the changes. After the code has been reviewed, use the “Review” button to complete the process. A -1 should be used if there are comments that need to be addressed prior to the code being merged in. A +1 should be used if the change looks good. Once two developers have reviewed the code, a committer can then review the change with +2 to merge the change into a baseline branch.
Note: A review of -2 from a committer will block the change from being merged in. The IP portion of the review is for preventing unauthorized 3rd party libraries from being packaged with OSEE. If no unapproved external dependencies are included in the change, a +1 should be given by at least one reviewer. The Verified portion of the review means that the change has been successfully built (i.e. the change does not break the build). If the patch successfully builds, a +1 should be given or a -1 if the build fails.
TODO: Add review checklist (make sure review design, does the change fit?) TODO: Add link to Gerrit Workflow
For quality purposes, all tests are run prior to checking in code changes. Gerrit can integrate with Hudson for the Verified portion of the review, but that is currently disabled due to the time it takes to run the build and tests. Multiple integration builds are created prior to release and are used by developers to check out new functionality as well as verify prior functionality. Once a build has been used by developers, it is promoted to user acceptance. A subset of users use the new build to verify more functionality. Prior to release, all tests must pass and all changes that went into the new version are verified by doing readiness reviews. These reviews are to double-check that changes we say are in a build are actually in the build that is marked for release.
TODO: Add tag description TODO: Describe builds (alpha, betas, release) - how to access TODO: Repository tags ? TODO: Add links to Eclipse Hudson TODO: Add build diagram for alpha, betas, etc
Deploying A Change
Depending on the type of action, care must be taken to deploy to an production site.
- Additions modifications of Artifact, Attribute and Relation types
- If changes to the type model are additions or minor modifications, they can be made directly in the production unified type artifact without down-time
- If the changes include deletions or renames of types, you will need to coordinate converting the database before making the changes to he types.
- Code changes
- If multiple releases of OSEE are deployed, code changes must be made in a compatible way such that the current release can continue to work while the alpha and beta releases are able to be tested and released to a smaller user audience. One way is to use the OSEE_INFO table to create a flag that allows old code to run until toggled. This allows the development and testing of the new code, but alpha and beta and full releases won't run the new code until the flag is toggled.
Followup changes during and after a release
- If changes are necessary during a release, such as table conversion or converting database attributes, you will need to create a ATS action labeled "During <release id> work". Then add a task in the task tab that explains what work needs to be done and references the Action that it's being done for. Provide enough detail that any OSEE developer can perform the task.
- If changes are necessary after a release, such as cleaning up deactivated or compatibility code, create a ATS action labeled "Post <release id> work". Then add a task in the task tab that explains what work needs to be done and references the Action that it's being done for. Provide enough detail that any OSEE developer can perform the task.
The OSEE Development process is designed to enable a change to be adequately reviewed and tested such that it could be quickly incorporated into the a next release. The releases attempt to facilitate this.
- OSEE Release
- Production Release
- Most Stable Release
- OSEE Release Candidate Beta
- Next release to be released to Production
- Used by smaller subset of user base
- OSEE Release Candidate Alpha
- Nightly snapshot of what has been released into the current RC branch
- Can be promoted to Beta when changes are ready
- OSEE Development Beta
- Trusted changes from the development line
- Normally only used by OSEE developers or users who need to test a single change
- Unstable and can be updated / restarted anytime
- OSEE Development Alpha
- Nightly snapshot off development line
- Only used by OSEE developers
- Most unstable and can be updated / restarted anytime
Building And Deploying
OSEE Builds and Deployment are done through Hudson. Snapshot builds are kicked off nightly and available the next morning. At anytime, an OSEE developer can select to promote an Alpha to Beta or Beta to Release by activating the promotion through Hudson.
OSEE is currently being deployed automatically to shared location.