Source Control Management and Release Process
Development Branches
/trunk -- main development branch. Small changes are done directly to this branch; larger changes are promoted here after being developed and debugged in a separate branch. Should be considered reasonably stable; it is expected to have bugs, but should never unusable and/or broken.
Code should never be checked into trunk that you know will materially break functionality for other users, because that blocks their development. Checking in code with well-delineated 'Known Issues' is OK, so long as those issues won't seriously impact another developer's coding or testing (i.e., the known issues deal with uncommonly-used parts of the code, uncommonly-encountered situations, or can be easily worked around).
In general, only small fixes and features will be checked directly into trunk. Most changes will be merged in from feature-specific branches once those changes are deemed done.
/branches/dev-* (e.g., dev-login, dev-immun-widget, dev-refactor-parsing) -- most development for new features or large changes will occur in a branch specific to that feature.
This isolates the development from the other developers, avoiding unnecessary conflicts and exposure to outside bugs. Creating a branch is not some big important formal event. The threshold for creating a new branch should be very low. And once the feature is complete and all code is merged back into dev, the branch should go extinct. Long-lived branches are OK, but they *must* stay in sync with dev in a timely manner. All new changes to dev should be back-merged into development branches weekly (at the worst). If another developer's changes conflict with yours, this is not an excuse to delay merging; talk to that developer sooner rather than later!
You can break anything you want in your own dev branch. This is the place to experiment with and explore things like refactoring or changing an interface.
Release Branches
Formal Releases
We plan to have frequent, official releases of code. Every one or two months sounds right. Releases do not have to be giant dumps of perfect code. The idea is to instead provide a steady trickle of small, but well-tested and readily-consumable features. Most releases will be interim (.1, .2, .3, etc.), but every so often we will have a major release (1.0, 2.0, etc.) that requires a higher degree of feature-completeness and grandiosity.
Each release will have an associated code freeze-date and release-date. Upon the freeze date, /trunk as of that date will be copied into /branches/release-candidates/[release]. From now until the release date, no new code will be allowed into the release candidate branch except important bug fixes. Then, upon the release date, the release candidate branch will be moved to /tags/releases/[release]. We may only go through this complete process for major releases, and for interim releases, simply forego the release candidate part altogether (copy /trunk directly to /tags/releases/).
Custom Project Releases
For certain projects with tight deadlines we may want a custom JavaRosa code stream. This situation arises because for a certain project some new features will be critical for that project while other new features will be irrelevant. The project needs to aggregate the critical features, but may want to exclude the irrelevant features simply because of the risk they pose of introducing bugs. If the feature is not needed at all, then why take on that feature's bugs? Clearly this is only an issue when deadlines are very tight, and we can't spare the time for all features to go through the normal testing/promotion/maturing process.
This situation is clearly undesirable but nevertheless may still happen and we should plan for it. The best example right now is development for GATHER. Why take the risk of merging in i18n support when we don't need it, hence dev-gather. I think these custom project versions should be handled as a special release. Once the deadline is deemed sufficiently tight to justify a custom release, copy /trunk to /branches/release-candidates/custom/gather. But during this 'freeze phase', in addition to bug fixes, also merge in new features from dev that are critical to the project. Once the code is deployed, move release-candidate/custom/gather to /tags/releases/custom-gather-jun08. Attaching versions to these releases would be silly.
Testing and Promotion
For promotion from dev-[specific feature] to trunk, the code should be complete and thoroughly tested and debugged. It is OK to have unresolved issues with the code, so long as those issues are well-delineated and documented, do not seriously impact the usefulness of the new feature (i.e., would not cause someone to consider the feature 'not done'), and would take an inordinate amount of time/effort to resolve. It is a subjective call: we don't want to unleash incomplete, buggy features on the other developers, but we also don't want to hold up other developer's exposure to new features just because of a few unimportant (or unresolvable) problems.
Code promoted to trunk will invariably have bugs, and just by virtue of being exposed to a wider group of developers, many of those bugs will get fixed with time. Therefore, the idea is that code promoted to trunk sits there for a while (a few weeks?) and goes through a maturing process as people fix these random bugs. After some (subjective, variable) amount of time passes, the code will be considered releasable.
Note: the time the code spends in trunk should not be considered a testing or QA phase aside from integration bugs! Thorough testing and debugging should be done before the code reaches trunk. The bug-fixing that takes place in trunk is just to provide an extra layer of insurance on top of an already-tested feature, as well as to find any integration bugs before that feature is released.
Check-ins
Before checking in any code to the repository, make sure you have run the Demo project's Integration and Unit test Ant target and made sure you have not broken any existing code
Try to check-in along feature-based lines. Don't group two disparate, unrelated features into the same check-in. Particularly try to commit bug fixes by themselves. Try to check in bug fixes by themselves, this makes grabbing the single change-set across branches easier.
Committing in bulk a bunch of small, loosely-related tweaks that people would have no interest in taking separately is OK.
Try to make your check-in comments as verbose as possible. Too much information is good! Say what you changed, how it works, why you did it and what issues you ran into.
Look before you commit! Don't let your IDE mangle the code with lots of auto-reformatting and useless code generation.
