Well defined code ownership is essential and fundamental. The ownership of code does not define proprietorship, but the responsibilities of creating, maintaining, and reviewing the code as a rightful owner. People other than the rightful owner can also maintain the code, but with prior permission from the rightful owner, and their changes must be reviewed by the owner before commit. In some cases, a review can also succeed commit. This is not a control but a discipline process so that the maintainer and owner are aware of the changes and agree on the changes. With proper assignment of ownership, as indicated in Table 1, the responsibilities for each source file becomes clear.

Ownership plays an important role in design conformance. Consider the following code fragment in sensor-node.ads where procedure Connect takes three parameters; Port, Node and Timing. Timing has been declared as Positive as in the system design. However, for some reason, a developer who is not the owner of this source file has made a change in his implementation. This changes Timing from Positive to Integer to allow negative values to indicate errors. While the developer thinks this is a great way to indicate errors, it will cause confusion, compilation errors, and non-conforming standards in system design and other source code which uses this package. With the ownership of code, the developer will know who to contact about the changes. Thus the developer can discuss this change with the original author (or designer) before committing.

package Sensor.Node is
   procedure Connect (Port   : in     DAQ.Data_Port;
                      Node   : in     DAQ.Node_ID;
                      Timing : in out Positive);
...
end Sensor.Node;

sensor-node.adb
sensor-node.ads
sensor_node_manager.adb
sensor_node_manager.ads
sensor_node_manager.gpr

sensor-activities.adb
sensor-activities.ads
sensor-calibrate.adb
sensor-calibrate.ads
sensor-realtime.adb
sensor-realtime.ads
sensors_array.ads

filter-fourier.adb
filter-fourier.ads
filter.adb
filter.ads

SVN can tell us what was changed, when the changes were made, and who changed it, but not why. It is useful to provide a detailed and meaningful explanation of why the changes were made. Table 2 shows some examples of bad and good logs.

Good commit log messages help the project team leader or manager compile a useful index of every commit (revision) from the post-commit logs to make maintaining, searching, and tracking revisions more convenient for all team members. This revision index is also useful documentation for tracking the history of development later on. Table 3 shows an example of an index of every revision with files involved and clear log messages.

When fixing a bug, add a regression test for it. Do a regression test and have both code and test result reviewed by others or the owner of the code before commit. Include regression test and the test result, if possible, to the change log.

When fixing bugs, do not follow documentation blindly, it may well be wrong. Test all bug fix and its behavior before commit.

Do not commit unrelated changes. Commit all related changes in one and unrelated changes in separate commit. Separate commits make it easier to maintain, track, review and if necessary to undo the changes.

This is a difficult question. It needs more senses and decisions to perform a good commit. Is there an urgency to commit minor correction of typo or grammar mistake in an English sentence? Or a missing semicolon that prevent the code from compiling?

Commit as often as possible. If losing current work is a concern, commit every time soon after work has been completed. Do not procrastinate commit. Commit on the same day as soon as the work has finished. But it is always a good habit to commit useful and working code. When adding new packages, determine a milestone where useful functionality has been completed. Commit when a milestone has been achieved.

package Nodes is

   procedure Initialization;
   procedure Finalization;

   procedure Add;
   procedure Delete;

   procedure Get;
   
   procedure Iterate;

end Nodes;

          

Avoid conflicts by updating often. The longer between updates, the harder it will be to merge changes with the changes done by other developers. Check the post commit messages to see if there is any changes relating to your current or vice versa. Commit immediately when a related update has been committed by other developers, otherwise inform the other developers about your work-in-progress so that they will be aware of your changes in relation to theirs.

Check for updates and run svn diff of the files to commit and check the changes on local work copy. Think twice before every commit. Review changes with other developers, team leader or project managers if doubt arises.

There are two types of review: pre-commit and post-commit review. Both have pros and cons. However, every commit must be tested and test results must be recorded and then reviewed. In pre-commit review, changes will not be available until everything has been tested, reviewed and committed while post-commit being the opposite. In post-commit review, non-performing functionality, bug fixes, non-conforming standards and undo is most likely to happen. It will affect many developers if they have already updated and started using the newly committed changes.

Every commit must be reviewed by the committer, the owner (if the committer is not the owner of code), system designer and a moderator. The review must be documented and approved before commit.

The first decision is when to branch? This can sometimes be an easy decision like "stable release", "major bug fix", etc. Most difficult decisions are most likely operating system dependence support. Consult fellow developers, team leader(s) and/or project manager.

Sometimes it will be difficult to decide where to branch. Give much consideration where to branch. For example, decide which revision is to be selected for alpha test. Figure 1 illustrates a branching where r111 has been selected for a branch, do a svn copy from r111 to, say, branch/alpha_test. Figure 2 illustrates a simple project with more complex branches are created and merged later.

Figure 1. Branching from the trunk

Figure 2. Complex branching in a simple project

The main trunk and the various branches should have an owner assigned who will be rsponsible for.

Branching produces a split in a code stream: different developers can be working in alternate universes of the same set of code. Changes are made independently to each stream. Merging brings changes back together to combine the streams. There are a number of reasons why you might want to use branches, and different reasons produce different kinds of branches. At some point when these reasons consolidate and a milestone achieved, these branches will merge.

Merging converges the branches back to the main trunk. Merging is the most complicated task of all in SCM and usually confusing when not careful.

During an on-going development, there are times when renaming a file or directory becomes necessary. One of the practice is to create a new branch and merge later but this method may cause confusion and sometimes may mess up the repository unnecessarily. When this happens, the best practice is to identify the components that need renaming and inform the entire team about the rename once the rename has been approved. Inform the entire team to commit their working copy, do a svn update and lock the affected for renaming.

In a large-scale software development, source code is not located in one single folder in a project. Source code may be located in multiple locations or folders under the project directory. The classification of source code according to folders usually is to organize the source code according to functions or family of functions. There are times when requirement or software specification has changed, the functions or family of functions will change according to the software design. It will be require to move affected source files to a new location for a better organization and categorization of source files.

For example, filter-fourier.adb and filter-fourier.ads were located in the project directory sensor/. The source files filter-fourier.ad* and related source files will have better organization after moving to a new sub-folder sensor/math/.