User Tools

Site Tools


iotivity_features_branches_and_release_process

Feature, Branch and Release Process

Overview

IoTivity is adopting a process to marshal contributions of any size into the project. This document will walk you through the process of suggesting a feature, design with review, implementation with review, acceptance and scheduling for release. There are milestones for your feature as well as milestones for release that are covered on this page.

Also see on the start page

  • Branching Policy
  • Versioning Policy
  • Release Cycle
  • Release Criteria
  • Release Schedule

Feature Milestones

Features come in many sizes and implications. The requirements for each are a little different. Trivial features are those that only affect a handful of files, easily expressed in a very short paragraph and have limited impact on the larger body of code. Minor and major features are larger, require a design and design review and may impact the entire stack operation. The process for each is covered here.

Where does it start?

It starts with an idea. A potential contributor should start by bringing their feature to the iotivity-dev mailing list. In this forum, the idea can be vetted and the size and scope can be determined. If the feature is trivial, such as adding a new property to a resource, it may be listed (see below). If after more discussion, the feature is considered minor or major, the contributor must capture the feature as a design document or design notes on the wiki so that it can go under further review.

Examples:

Feature (Design) under Review

After the design is posted to the wiki and the posting has been announced on the mailing list, it is considered under review. At this time discussion should continue on the mailing list and the author should continue to edit the design on the wiki based on feedback. Once all comments have been addressed, the feature may be listed (see below)

Feature Listing

Listing your feature just means that it is tracked in Jira. When ready, the contributor or requester of the feature should create a Jira ticket (enhancement) to track the feature. Jira will be used to track who is working on it and to provide status. Jira allows “child” tickets to allow reporting of progress. Using this feature is highly encouraged. If there is an associated design document, it is recommended that the URI to the design document to be included on the Jira ticket AND that the design document refer to the Jira ticket(s).

If the feature requester is also going to be the contributor, it is recommended that they assign the Jira ticket to themselves.

See Jira (http://jira.iotivity.org) and IoTivity Feature Development

Feature in Progress

Once there is a Jira ticket and a contributor is ready to implement, the contributor should request a feature branch from the domain maintainer. When requesting, be sure to provide the Jira ticket number so the maintainer can determine whether the feature is ready (ie. design covered the feature and has been reviewed if needed). Again, it is best practice to note the branch name on the Jira ticket as well as post progress to the Jira ticket comments.

At this point, the contributor may push change sets to gerrit for community review. The contributor should be sure the invite the domain maintainer and any other members that may have participated in the design discussions. After addressing all of the concerns of the maintainer, the maintainer will give the review a +2 and submit the code.

It is best to follow the “Commit Early, Commit Often” practices. This keeps your commits small and easy to review. However, it is recommended to always commit meaningful amounts of code. For instance, committing a C structure without logic, interface or explanation is not meaningful to reviewers.

References

Feature Complete

To be feature complete, a contributor must meet the following criteria:

  • Code complete
  • Unit tests
  • Sample application written, if needed
  • Validated in build environment
  • Testing complete
  • Documentation updated, if needed

When you are ready, send a note to the iotivity-dev mailing list AND the maintainer to announce the feature readiness. The maintainer may merge the feature branch into the master branch and/or ask you to make changes including rebasing, squashing, etc. to prepare the feature for merger. This can be frustrating at times. So, remember to be kind to your maintainer. They are your friend.

When merging is complete, the maintainer will announce the merge event to the iotivity-dev mailing list and update Jira and the wiki as appropriate.

At this point, congratulations! Your now a contributor.

Release Milestones

The IoTivity Steering Group has agreed to two types of releases. The first and most common is the minor release. A minor release will increase the minor version or revision version numbers. For instance, consider the following:

  • 0.9.0 ⇒ 0.9.1 (Revision, minor release)
  • 0.9.6 ⇒ 0.10.0 (Minor version, minor release)
  • 0.9.7 ⇒ 1.0.0 (Major version, major release)

The goal and process for each of these is different. Each is discussed below.

Minor Releases

The goal of the minor release is to provide timely updates (currently on a two month cadence) to IoTivity including fixes and any available features to date. Generally, these do not align to standard changes and should be compatible over the air but may contain some changes to the programming APIs. The following sections describes the milestones for a minor release including criteria to reach the milestone and the tasks, roles and responsibilities that the milestone triggers..

Release Feature Freeze

The feature freeze date is the cut-off date for features to make it into the next release. For a feature to be accepted into a release, it must be feature complete, reviewed and accepted into the master branch before the cut-off date. Any feature that is pushed into master AFTER the cut-off date will naturally slip to the next release. The feature freeze date will be announced at least 30 days in advance by the IoTivity Release Function Lead.

At feature freeze, the following steps will be taken:

  • A release branch will be created from master by one of the maintainers.
    • The branch name will follow the release name ie. 0.9.1-dev
    • A tag will be created immediately marking the release candidate 0.9.1-RC1
    • The branch and tag will be announce on the iotivity-dev list
  • Test engineering will begin system testing on the release
  • Release management will start writing release notes based on the features which made the release
  • Maintainers will only accept bug fixes into the release branch.

To fix a bug in the release branch, you should first fix it on the master branch. Once verified on the master branch, notify the maintainer that the fix should go into a release branch. If the maintainer agrees, they will attempt to cherry-pick the change set to the release branch. They may be exceptions where a fix is only a work around for a bigger issue in the release. In this case, it is the maintainer decision to accept a fix directly to the release branch.

Release Quality Report

About 5-7 days later, depending on the size of the release, test engineering will provide a status report on the quality of the release. Base on the results, a final date will be announce for the release to give time for any fixes for the release branch.

At feature freeze, the following steps will be taken:

  • A release branch will be created from master by one of the maintainers.
    • The branch name will follow the release name ie. 0.9.1-dev
    • A tag will be created immediately marking the release candidate 0.9.1-RC1
    • The branch and tag will be announce on the iotivity-dev list

Code Freeze

Once all prevailing issues have been addressed. The release code is considered frozen and the following steps will be taken:

  • tar ball will be created by the <enter role here>
  • documentation update by the <enter role here>,…
  • Each contributor should create feature release notes and send them to the <TBD> for inclusion in the final release notes.
  • A release blog entry will by posted to the IoTivity web site and a release announcement will be made to the iotivity-dev list by the IoTivity Release Function Lead

Major Releases

Major releases are intended to capture a collection of features for a release with more rigorous testing. Since the features list is fixed, a major release is feature driven and the release date may be adjusted to ensure a complete set of functionality.

The process for a major release is the same for a minor release except that the release process is repeated weekly until all of the features are completed and the quality control targets are met for the major release. So, in cases where a feature does not make the feature freeze date for a major release, the quality/documentation/etc. process continues for the features that are complete. When any missing features are completed, the quality/documentation/etc. process begins again including the late feature.

Regarding Defects

Fixes for defects are a high priority contribution. Generally, patches sent to gerrit for review that address defects must have an accompanying Jira ticket. The ticket should include the nature of the problem and the steps to reproduce it so that a maintainer can validate, if necessary, that the change set addresses the issue. Be sure to mention the Jira ticket in the commit comments.

As with all things, there is an exception to this guidance. If the fix is targeted and obvious, the fix can be sent to gerrit without a Jira ticket. To be considered targeted, the change set should fit on one screen (one unit and a handful of change lines of code). To be considered obvious, the change set should be clear with minimal explanation. The contributor should provide a complete and clear explanation in the commit comment. The decision on whether the change set meets this criteria ultimately belongs to the maintainer. This types of fixes would include:

  • Buffer overruns or off-by-one loops
  • Localized memory leaks
  • Other resource leaks (closing file)
  • Parameter checks
  • Corrections to return values

Frequently Ask Questions (FAQ)

Features

iotivity_features_branches_and_release_process.txt · Last modified: 2015/07/06 19:15 by Patrick Lankswert