PyMite Development Process

Author: Dean Hall
Id:DevelopmentProcess.txt 493 2010-06-06 16:23:09Z dwhall256

Purpose

This document describes the process used to make changes to files in the Python-on-a-Chip project. In doing so, it serves as a how-to manual for the developer and can be ignored by the user.

This document is incomplete and subject to change. Please suggest improvements.

Overview

Software quality is enhanced when the project developers consistently employ a defined software process. The process should enhance the development of the software and not burden it. This process is a typical branch-based development process that uses Subversion and Google Code. If this document does not explain your question, please ask on the maillist. Since long process documents often go unread, this document is as concise as possible.

Here is a brief description of the process:

  1. Create an Issue
  2. Do the Work
  3. Link Commits and Messages
  4. Keep in Sync with Trunk
  5. Run tests
  6. Post for Review
  7. Merge to trunk

Create an Issue

Create a new issue to capture and document enhancments and defects.

The following table explains what to enter in the fields when creating an issue:

Field What to enter Example
Summary Short sentence starting with verb that explains the issue Enable compiler warnings as errors
Description A longer explanation of the problem possibly with example code that exercises or exposes the issue.  
Status If you want it, leave it as Accepted. Otherwise clear the box. Accepted
Owner If you want it, take it. Otherwise leave it blank. dwhall256
Labels Select the proper label-type from the three that are given: Type, Priority and Component. Type-Defect Priority-Medium Component-pmvm

The Summary field is often copied into the release notes' change log, with the opening verb changed to the past tense. Conceive your Summary from that point of view. The Milestone- label is used by the project manager to know what issues should be resolved for what releases. Leave out the Milestone label unless you've been told to do otherwise. Select the most appropriate component from the Component- list. Even if the resolution touches more than one component, select the one that applies best.

Do the Work

The developer must first obtain a local copy of the code. If the work only involves a small change, or a similar small change across many files, then the work can be done on a working copy of trunk/:

svn co https://python-on-a-chip.googlecode.com/svn/trunk/ --userid YourUserId

If there are more than a few changes, make a branch to work in and check out a local copy:

svn cp https://python-on-a-chip.googlecode.com/svn/trunk/ \
       https://python-on-a-chip.googlecode.com/svn/branches/issue_0NNN_userid_brief_description \
       -m "Issue #NNN: creating branch for work"
svn co https://python-on-a-chip.googlecode.com/svn/branches/issue_0NNN_userid_brief_description --userid YourUserId

If the work involved is a defect, the developer should create the smallest test possible that exposes the defect. This regression test should be added to the project's automated test system:

svn add src/test/system/tNNN.c src/test/system/tNNN.py

If the work required a significant architectural change, a document should be created which explains the design of the work. This document should be composed in reStructuredText and added to the project's automated documentation build system docs/src/:

svn add docs/src/NewDocumentTitle.txt

Keep in Sync with Trunk

While doing the work, if the trunk is updated, you should merge those changes into your branch so that your working copy is always up-to-date. Doing this merge-forward step avoids the problem of when you mainline your branch and your changes don't work with the modified trunk. If you are working on a local copy of trunk/, then staying synced is easy: just use the command:

svn update

Pay attention to the output of this command to see if there are conflicts that must be resolved.

If you are working on a branch, there are two ways to stay in sync with trunk/. Merging trunk to your local copy and then commiting your branch is recommended:

svn merge http://python-on-a-chip.googlecode.com/svn/trunk/ .
svn ci -m "Issue #NN merging trunk to branch"

Run Tests

The project has an automated test system that is run by typing the following from the root of the project:

make check

These tests must pass before an issue may be mainlined, but passing these tests is not the only qualification for mainlining. If the work done impacted any of the project source code, then testing should also be performed on the relevant desktop and target platforms. If the issue describes a defect, then you should already have a test in the automated test system, so that test will be run by make check.

Post for Review

Note

The Google Code review process should NOT be used.

After the developer does the work, syncs to the trunk and runs the tests, he posts the changes for review. If the changes were few and the developer made the changes on a local copy of trunk, then he should create a patch file like so:

svn diff > issueNNN.patch

He should send an email to the p14p developer mailling list and attach the patch file.

If the changes were many and the developer worked on a branch, then the developer must ensure that every commit he made is mentioned, via the rYYY syntax, in the issue. This way, the developer can simply send the URL of his issue to the maillist for review:

http://code.google.com/p/python-on-a-chip/issues/detail?id=NNN

Reviewers give polite and professional feedback to the developer within 48 hours or provide an estimate of how much longer it will take to review the changes.

The developer applies all the feedback and re-tests the branch.

Merge to Trunk

Merging to trunk/ happens after the change-set is reviewed, feedback is integrated and the tests pass. Ensure the branch is in sync with trunk, per the section above. Then revert to a clean copy of trunk:

svn switch https://python-on-a-chip.googlecode.com/svn/trunk/

Merge your branch into the working copy of trunk:

svn merge https://python-on-a-chip.googlecode.com/svn/branches/issue_0NNN_userid_brief_description .

Build, test and verify the modified working copy, then commit it to the trunk:

svn ci -m "Issue #NNN: mainlining branch issue_0NNN_userid_brief_description"

Add a comment to the issue:

rYYY: merged branch to trunk

and set the Status field to Fixed.

Finally, announce that the issue is fixed on the mailling list.