User Tools

Site Tools


iotivity_features_branches_and_release_process

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
iotivity_features_branches_and_release_process [2015/06/05 18:09]
Patrick Lankswert [Regarding Defects]
iotivity_features_branches_and_release_process [2015/07/06 19:15] (current)
Patrick Lankswert
Line 1: Line 1:
-====== ​(Proposed) ​Feature, Branch and Release Process ======+====== Feature, Branch and Release Process ======
 ===== Overview ===== ===== 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. 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 ===== ===== 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. 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? === === 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 more detailed ​discussion is needed, the contributor ​should ​capture the feature as a design document or design notes on the wiki so that it can go under review.+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.
  
-TODOAdd link to an example+Examples: 
 +  * [[https://​wiki.iotivity.org/​resource_directory]] 
 +  * [[https://​wiki.iotivity.org/​multi-phy_easy_setup]]
  
 === Feature (Design) under Review === === 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) 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)
- 
-TODO: Need to define time under review. Silent consent allowed? 
  
 === Feature Listing === === Feature Listing ===
Line 20: Line 26:
 If the feature requester is also going to be the contributor,​ it is recommended that they assign the Jira ticket to themselves. If the feature requester is also going to be the contributor,​ it is recommended that they assign the Jira ticket to themselves.
  
-TODOAdd link to Jira site.+See [[http://​jira.iotivity.org| ​Jira (http://​jira.iotivity.org)]] and [[IoTivity Feature Development]]
  
 === Feature in Progress === === 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. 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
 +  * [[https://​sethrobertson.github.io/​GitBestPractices/​| Git Best Practices]]
  
 === Feature Complete === === Feature Complete ===
Line 33: Line 46:
   * Testing complete   * Testing complete
   * Documentation updated, if needed   * Documentation updated, if needed
-At this point, the contributor may push 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. 
  
-TODO: Talk about the merge process from the feature branch ​to the master branch.+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 ===== ===== 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: 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:
Line 57: Line 73:
   * Release management will start writing release notes based on the features which made 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.   * Maintainers will only accept bug fixes into the release branch.
-  + 
-TODO: It has been recommended by Erich that general ​bug fixes should ​be delivered to masterverified ​there and cherry-picked ​to the release branch. They may be exceptions where a fix is only a work around for a bigger issue. In this case, it may make sense that a fix would only go to 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 === === Release Quality Report ===
Line 78: Line 94:
 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. 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 different from a minor release and will be detailed here in the near future.+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 ===== ===== 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) ===== ===== Frequently Ask Questions (FAQ) =====
  
iotivity_features_branches_and_release_process.1433527746.txt.gz · Last modified: 2015/06/05 18:09 by Patrick Lankswert