Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Code Maintenance Guide

Maintaining code in large projects can be a difficult process, as the desire to get things done combined with stylistic differences between team members can quickly lead to an unmanageable degree of code entropy. Until Maxwell's Demon learns how to code, here are a few suggestions for how to slow the inevitable slide towards chaos.

General considerations

  • Make sure that the intended change is necessary, is consistent with the package philosophy, and is clearly defined. The best way to avoid code rot is to simply not make any unnecessary changes.
  • Consult the owner of the affected package or module. Rather than trying to make sense of the design philosophy of a package or module directly, it is often easier to go to the source. In addition to typically being both faster and more informative than an inspection of the code and documentation, the owner of a particular piece of code may be aware of the issue and of any existing effort to address the problem. Also, it may be that what appears to be a bug is actually an intended and known consequence of improper use which is simply lacking appropriate documentation. Finding the owner is easy, as their name(s) should be in the Author clause of the module header.
  • If discussion with the code owner reveals that a change is indeed necessary, decide whether you have enough domain knowledge to make the change in a way that is consistent with the philosophy and design of the involved package or module. If not and time is an issue, it may be best to reassign the task to the code owner. Otherwise, further discussion may be a valuable asset in understanding the problem and the best way to approach it.
  • Make every attempt to be consistent with the style of the existing code. This includes spacing and indenting, naming conventions, and careful modification of any associated comments. One benefit of code ownership is that it tends to result in a consistent code format, and this can be of tremendous benefit to readability.
  • Implement the simplest possible solution to the problem at hand. Do not refactor for theoretical future scenarios or attempt to be overly clever. If no simple solution presents itself, ask others for suggestions. Often, simply describing a problem will lead to new insight into the problem. If not, perhaps the ensuing discussion will be helpful. The code owner is a good person to ask for advice, as there is a good chance they have considered the issue before.
  • Include an explanation of any changes in the associated ticket. If no ticket exists, create one. It can often be useful for future maintainers if a list of affected modules is attached to the ticket, as well as any test cases that might be used to reveal the original problem or verify the fix. If the issue was discussed in a forum where logging is an option, consider including the discussion as a comment in the ticket.

Commit Policy

Terms

  • Maintainer : Original author of code, or person later assigned maintainership of a given portion of code.
  • Project lead : This is at any given time, the current administrative and technical leading group of Tango. Currently it consists of Kris Bell(principal developer of Mango), Sean Kelly (principal developer of Ares), Lars Ivar Igesund (administrative resource).
  • Contributor : This a person that at some point have contributed to Tango, either through testing, writing of documentation, code patches or Maintainership.
  • Community : This is the group of contributors and/or people at any time using Tango.
  • Private branch : A private branch in the repository where a developer can test and develop new features.
  • Official branch : A branch of trunk to make space for a new major version in trunk.
  • Trunk : Where the current main development of Tango occurs.
  • Patch : A change to trunk or an official branch, stored as a patch file.
  • Commit : In this document, a commit is first of all considered to be a change to production code, that is within the internal lib/ tree, or in tango/, either in trunk or in an official branch. Consider it also to apply to larger changes to documentation (obvious typos are usually not of that sort), repository structure, tools and example code.

Policies

  • All commits of any significance are to be accompanied by a commit message saying what was fixed or added, and include the relevant ticket number if applicable. This to facilitate the usage of the svn log for change logs for new releases.
  • Very obvious bugfixes (single line fixes) and compile fixes, may usually be committed by anyone with commit privileges. This also apply to simple documentation fixes.
  • Semantic changes to a module's code, for instance change in behaviour, or addition of new functionality, should only be committed by that module's Maintainer, and will thus need to be accepted by that person. If it also will affect other parts of the repository, it will first need to be discussed with the project lead which again should choose to ask the community if the matter is considered to be large and/or controversial.
  • If semantic code changes are proposed to the Maintainer, but the nature of the change is thus that it cannot be immediately rejected or accepted, a patch need to be created. This should be committed to the patches/proposals/ directory of trunk or the given branch, whichever applies. A ticket describing the issue or proposal that the patch fix should be created (unless it already exists), and the patch should be referenced in the ticket. The acceptation process for the patch, will otherwise follow the same process as for semantic changes.
    • Accepted patches will after they are applied, be put into patches/proposals/accepted/.
    • Rejected patches will be put into patches/proposals/rejected/.
    • Tickets will contain necessary argumentation and/or reasoning for acceptal/rejection.
    • A listing in the directories above should contain a mapping between patch and ticket number, such that it will be easy to see why a given patch has been applied or rejected.
  • Failure to oblige can (and most likely will) result in reverts.
  • It has been proposed to change VCS to something like Monotone at a later date. If so happens, Tango will move towards commits of only signed-off patches for the main branches.
  • Private branches don't pertain to the above policies, as long as the committer has actual commit privileges. Such branches can be used to develop a patch for later consideration.