Project Dune:Code Management

From PDune

Jump to: navigation, search

Code management describes the processes for starting, making, reviewing and allowing code changes. Please note that coding standards and architecture are described in the Development Guide, so these are not applicable to code management.

This section deals with how the repositories are organized, how to start work on a particular problem and how to communicate or publish your current activities to the rest of the group. So a lot of these processes are related to communicating changes in the code to the group and archiving this for future reference.


Contents

Repository Organization

We use subversion as the code repository. This is a very flexible code repository with lots of features. Subversion supports the idea of branches and tags. Tags are used to establish baselines, which are used to provide the ability to easily re-build releases in the future and to be able to browse through the source code and compare baseline versions of source code files.

It is very undesirable to maintain code changes on the local computer, so daily commits are a necessity to preserve the work. This requires each developer to assess the time that is necessary to finish the complete work. If the work spans a large number of days and the functionality touches certain pieces of code that are in general released, it may be necessary to create a branch and work within that branch until all the changes can be merged back into the HEAD section of the repository. The branch will allow the developer to commit the work daily so that changes will never get lost. The release managers then always have the ability to create new releases from the HEAD of the repository without being impacted.


Basics about Subversion

The following information is extracted and adapted from the SVN book.

Branches are created as follows (with auto-commit using the -m flag): 

  svn copy https://pdune.svn.sourceforge.net/svnroot/pdune/trunk https://pdune.svn.sourceforge.net/svnroot/pdune/branches/PDUNE_X_Y_Z \
    -m 'branching X.Y.Z. for development of CRxxxxx'

And subsequently checked out: 

   svn checkout https://pdune.svn.sourceforge.net/svnroot/pdune/branches/PDUNE_X_Y_Z

It is recommended that you subscribe to the pdune-svn mailing list. This list is available for developers only and will send an email after each commit. This will allow you to track changes and gives you the version numbers to use when you wish to merge certain changes. To merge from one branch (or revision) to another, use the following commands. xxx is a previous version number and yyy is the version number that was assigned for the commit of another person working in another branch. These commands allow you to synchronize between branches, which will help significantly to prevent conflicts at the end of the overall merge effort. It is recommended to synchronize daily, even when working in a separate branch. This merge will effectively bring over changes in HEAD or other branches to your branch, so you will stay updated with latest developments. The end merge that you will perform to merge your changes in your branches with the HEAD is then a whole lot easier. Make sure you are in the correct (trunk) directory when issueing the following commands: 

   <username>@/workspace/pdune/trunk> svn diff -c xxx https://pdune.svn.sourceforge.net/svnroot/pdune/trunk
    <username>@/workspace/pdune/trunk> svn merge -c xxx https://pdune.svn.sourceforge.net/svnroot/pdune/trunk
    <username>@/workspace/pdune/trunk> svn commit

And when the work is finished and the changes on the branch are committed, check out the HEAD branch and merge the changes from the side branch into HEAD: 

   <username>@/workspace/pdune/trunk> svn checkout https://pdune.svn.sourceforge.net/svnroot/pdune/trunk
    <username>@/workspace/pdune/trunk> svn merge --dry-run -c yyy https://pdune.svn.sourceforge.net/svnroot/pdune/trunk
    <username>@/workspace/pdune/trunk> svn merge -c yyy https://pdune.svn.sourceforge.net/svnroot/pdune/trunk


Starting work

So let's say we have identified the need for making code changes or additions. The procedure for starting work on this is as follows:

You should always create a CR first before working on any code. This CR is used to link external information systems with the commits in the code. When you use the CR number in the commit log statement, tools like Eclipse can generate code annotations that allow you to track back the CR number in other information systems and identify the reason for certain changes and other contextual information.

Project Dune uses the SourceForge tracker to register this information. Choose between bug, feature request or support request and describe the reason for the changes you are about to make. Make sure to use this CR number in your commit logs when you commit the changes.


Code Reviews

This article or section needs review by members to improve the quality of content. Not all project members may agree with this section.


You can assist by discussion this page on the talk pages.

Since all commits to the repository are published through the pdune-svn mailing list, it is easy for people to identify when certain commits are made that touch their own areas. The suggested method for review is to find out which areas are of your interest and review the code changes of other people.

The approach adopted is "commit first, then review and comment". This is because we're working remotely, which makes face-to-face conversations very difficult.

There are a number of reasons to conduct code reviews:

  • Establish consensus on approaches taken
  • Share knowledge in programming and engineering
  • Consider other, perhaps better alternatives for the implementation
  • Improve the quality of the actual code
  • Prevent unnecessary bugs that are easy to catch before they hit production

In cases of doubts and/or comments, send a message to the pdune-developer list, detailing the revision number of the commit and the CR number for the change. Copy the particular area of interest if required and construct your comments around it. If the discussion gets too involved, please continue the discussion in a private message exchange or consider a real-time communication session through IM or IRC.


Automated Code Quality Tools

There are a number of automated tools available that will help you to improve the overall quality before you commit your changes. They will make the code more readable and might catch certain obvious bugs. Obviously, automated tools cannot help very well in the approach for the implementation.

  • FindBugs
  • Eclipse Code Metrics
  • The "correct indentation" feature of Eclipse. Select the code to automatically indent and hit Ctrl+I or select the option from the popup menu.


Release building

As the Release Guide shows, we establish tags for each release. The tag is in the format "PDUNE_X_Y_Z", where X, Y and Z are the major, minor and revision version numbers. The tag is applied as follows: 

   <username>@/workspace/pdune/trunk/> svn copy https://pdune.svn.sourceforge.net/svnroot/pdune/trunk \
    https://pdune.svn.sourceforge.net/svnroot/pdune/tags/PDUNE_1_1_0 \
     -m 'tagging 1.1.0'

Then follow the release guide for building and publishing the release.

Retrieved from "http://projectdune.org/Project_Dune:Code_Management"
Personal tools