Purpose

This document describes the process used to make changes to the PyMite project. In doing so, it serves as a how-to manual for the PyMite developer and can be ignored by the PyMite 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 takes ideas from popular standard processes, with specific attention to Divmod's process, UQDS. If this document does not explain your question, refer to UQDS for the answer. Since long process documents often go unread, this document should be as concise as possible.

Here is a brief description of the process:

1. All changes must be documented, so create a ticket in Trac.
2. Do the work and provide a change-set for review.
3. Apply feedback from review, run tests and mainline.

Creating a Ticket

Submit all enhancements, defects, issues and tickets to the Python-on-a-chip Google Code site. Or go straight to create a new ticket.

The following table explains what to enter in the fields when creating a ticket:

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.

Doing the Work

If the work involved is a defect, the first step is to create the smallest test possible that exposes the defect. This regression test should be put into the project's automated test system src/test/system/.

If the work involved is an enhancement or a defect that requires a significant change, a document should be created which explains the architecture or design of the work. This document should be composed in reStructuredText and put into the project's automated documentation build system docs/src/.

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 the project trunk/ and the code review can be performed by attaching the output of svn diff to the ticket.

If there are more than a few changes, make a branch to work in:

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"

If you've already made changes to a working copy that isn't the new branch, it's easy to switch to the new branch and keep your changes:

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

During this phase, 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. Use the following command to merge-forward changes from the trunk:

svn update

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

Testing

The project has an automated test system that is run by typing make check. These tests must pass before a ticket can be mainlined, but passing these tests doesn't automatically mean a ticket is mainlined. If the work done impacted any of the project source code, then testing should also be performed on all targets, desktop and device. If the ticket described a defect, then you should have already made a test to put in the automated test system, so that test will already be in the set run by make check.

Reviewing

After the developer does the work and runs the tests, he checks in the branch. When the developer goes to post the differences for review, the differences should be from the head of the branch to the head of the trunk. It is a common mistake to take the difference from the head of the branch to the origin of the branch. This is a mistake because the trunk may have progressed since then and the developer should have merged-forward throughout the lifetime of the branch. Diffing to the head of the trunk shows that the developer kept up-to-date with the current code and gives the proper change-set to merge the branch into the trunk. The following command line will create a diff between the head of the branch and the head of the trunk:

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

Reviewers give feedback to the developer, possibly in the form of a patch file-- if the volume of feedback is large--that would be applied to the head of the branch.

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

Mainlining

Mainlining happens after the change-set is reviewed and the feedback is integrated and the tests pass. Mainlining is the process of applying the branch to the trunk. This is one of the few not-so-intuitive processes of Subversion. Start by ensuring your branch has merged-forward all changes to the trunk since the branch was created:

svn up

Switch the working copy of the branch to the project trunk:

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

Merge the differences between trunk and the branch into your working copy:

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

Inspect and test the working copy, then commit it to the trunk:

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

Finally, update the ticket to set the Status to Fixed.