This is an old revision of the document!
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.
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.
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.
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)
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.
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.
To be feature complete, a contributor must meet the following criteria:
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.
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:
The goal and process for each of these is different. Each is discussed below.
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..
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:
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.
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:
Once all prevailing issues have been addressed. The release code is considered frozen and the following steps will be taken:
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.
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: