Author: | Dean Hall |
---|---|
Id: | DevelopmentProcess.txt 493 2010-06-06 16:23:09Z dwhall256 |
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.
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:
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.
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
Every time the developer commits code to either trunk or his branch, he should add a commit message such as the following which lets Google Code hyperlink the commit to the issue:
svn ci -m "Issue #NNN: checking in on branch"
or:
svn ci -m "Issue #NNN: mainlining directly"
Then, the developer should describe the changes in a new comment in the issue. The developer should prefix this comment with the revision number that resulted from the commit action, like so:
rYYY: Fixed a null pointer in src/vm/interp.c
Where YYY is the number of the revision that resulted from the check-in. These two little text snippets create a precise two-way linkage between the physical changes to the code and the aggregated notes of an issue, resulting in a documented process that is easy for others to follow.
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"
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.
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.
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.