--- mitgcm.org/cvspolicy.html 2000/07/02 15:04:45 1.6 +++ mitgcm.org/cvspolicy.html 2001/02/17 17:08:40 1.10 @@ -1,131 +1,198 @@ + + + + + MITgcm CVS policy - - MITGCM CVS policies - =================== - -o Introduction - - This note describes policies that apply to the MITGCM CVS repository - -o Why have a policy? - - CVS itself is a liberal free-for-all product that can be used in a variety - of ways. It is designed to provide a system for storing arbitrary files - in a way that allows the change history of the individual files to be - tracked. If CVS is used without any other policy the result can be a - collection of files each of which has complex, multiply branched set of - interelated versions. This sort of CVS repository can be come like a - library where books are simply stored in a huge heap. Although nothing is - actually lost, the task of finding a coherent collection of material soon - becomes impossible. - - The policies we employ address two areas - 1. Maintaining an orderly and easily identifiable, coherent set of - evolving "products". - 2. Allowing concurrent, on-going development of product components. - -o Development trees and checkpoint trees - - A directory within the MITGCM repository resides under either the - development branch or the checkpoint branch. Files within each branch - follow different policies. - -o Development tree policies - - Development trees are intended to be flexible areas where arbitrary files - can be stored with multiple versions, many branches supporting multiple - ongoing streams of development. Development trees have no policies in - place to control complexity. Development trees might be associated with - a particular person, a certain project or a particular special piece of - work. These trees are intended to be useful areas for storing current - work and for archiving partially finished work so that it doesn't get - mislaid and so that some record of the development history can be easily - maintained. The only policy that applies to development trees is that - this style of tree is not intended to be used for providing a - "checkpoint" distribution. Tagged configurations of tools built from this - style of tree can be distributed, but because these trees do not have any - polcies regarding testing of functionality, platform coverage or - documentation these trees are not allowed to form the basis of - "checkpoint" distrbutions or formal "releases". Other policies can - be defined by individuals users of these trees but there are no further - global policies. The MITGCM repository development_tree/ subdirectory is - reserved for holding development trees. Development trees also serve as - experimental areas for exploring new code management policies. - -o Checkpoint tree policies - - Checkpoint trees are intended to provide structured storage areas for - holding code that is intended for open distribution and is to be readily - downloaded. There are policies governing the operation of these trees - which are designed to ensure that distributed codes are clearly - identified and meet certain levels of quality. - - 1. Check-out - - Just do it! Two mechanisms are available. cvsanon for read only access - and regular cvs co .... for read/write access. - - 2. Check-in. - - The code check in procedure for a "checkpoint" tree is as follows - 2.1 Check out the latest main branch revision. - 2.2 Merge your changes into that revision. - 2.3 Build and validate new code. - 2.4 Check that there have been no further changes to the - repository. Repeat from 2.1 if repository has changed. - 2.5 Get clearance from other developers to check in your changes. - 2.6 Check in your changed main branch. - 2.8 Build and validate the new changes. - 2.9 Tag code as "checkpointNN". Add records to docs/tag-index. - 2.10 Build and validate test cases (see testing). - 2.11 Create and install checkpointNN.tar.gz - - 3. Testing - - Things in a checkpoint tree require a test case that - can be used to validate the component. - - 4. Checkpoint tagging - - No code should be left in limbo. Checking in code and then - leaving it in the repository untagged is bad. When you check - in code you are creating a new checkpoint. That means you don't - check in some code which you "know" works 100% and then go away - for two weeks. When you start checking in code you make sure - you have time to do the process end-to-end as described in section - 2. - - 5. Release tagging - - Releases are only based on checkpoint tree code. Maintenance fixes - to releases are also maintained within the checkpoint tree. Files - within a release must have accompanying documentation. The form of this - documentation depends on the file type. - - 6. Branches - - Branches are to be used for bug-fixes and code patches to releases - only. All other changes e.g. totally new features, bug-fixes to - checkpoints are introduced by moving checkpoint levels forward. The - only historical code maintenance that is employed is for fixes and - patches to formal releases - not checkpoints. - -o These policies are causing me a big problem, what can I do? - - The policies are not enforced by any mechanism other than mutual - agreement! If you think the policies are not appropriate then let us know - and we can discuss changing them. However, if you simply ignore the - policies regarding the checkpoint_release trees then your code may be - removed and/or your access revoked. - -o What about bitkeeper - - We are looking at bitkeeper (www.bitkeeper.com). It looks cool, but - policies are still important. Any experience, suggestions let us know. - Watch this space! + + +
+

+MITgcm CVS policy

+ +

+Introduction

+This note describes policies that apply to the MITGCM CVS repository. +

+Why have a policy?

+CVS itself is a liberal free-for-all product that can be used in a variety +of ways. It is designed to provide a system for storing arbitrary files +in a way that allows the change history of the individual files to be tracked. +If CVS is used without any other policy the result can be a collection +of files each of which has complex, multiply branched set of inter-related +versions. This sort of CVS repository can be come like a library where +books are simply stored in a huge heap. Although nothing is actually lost, +the task of finding a coherent collection of material soon becomes impossible. +

The policies we employ address tree areas +

    +
  1. +Maintaining an orderly and easily identifiable, coherent set of evolving +"products".
    2. + +
  2. +Allowing concurrent, on-going development of product components.
    3. + +
  3. +Making the integration  of achieved developments easy, rapid, organized +and clear.
    4. +
+ +

+Development trees and checkpoint trees

+A directory within the MITGCM repository resides under either the development +branch or the checkpoint branch. Files within each branch follow different +policies. +

+Development tree policies

+Development trees are intended to be flexible areas where arbitrary files +can be stored with multiple versions, many branches supporting multiple +ongoing streams of development. Development trees have no policies in place +to control complexity. Development trees might be associated with a particular +person, a certain project or a particular special piece of work. These +trees are intended to be useful areas for storing current work and for +archiving partially finished work so that it doesn't get mislaid and so +that some record of the development history can be easily maintained. The +only policy that applies to development trees is that this style of tree +is not intended to be used for providing a "checkpoint" distribution. Tagged +configurations of tools built from this style of tree can be distributed, +but because these trees do not have any policies regarding testing of functionality, +platform coverage or documentation these trees are not allowed to form +the basis of "checkpoint" distributions or formal "releases". Other policies +can be defined by individuals users of these trees but there are no further +global policies. The MITGCM repository development_tree/ sub-directory +is reserved for holding development trees. Development trees also serve +as experimental areas for exploring new code management policies. +

+Checkpoint tree policies

+Checkpoint trees are intended to provide structured storage areas for holding +code that is intended for open distribution and is to be readily downloaded. +There are policies governing the operation of these trees which are designed +to ensure that distributed codes are early identified and meet certain +levels of quality. +
    +
  1. +Check-out
    2. + +
    Just do it! Two mechanisms are available. cvsanon for read only access +and regular cvs co .... for read/write access. +
  2. +Check-in
    3. + +
    The code check in procedure for a "checkpoint" tree is as follows +
      +
    1. +Check out the latest main branch revision.
      2. + +
    2. +Merge your changes into that revision.
      3. + +
    3. +Build and validate new code.
      4. + +
    4. +Check that there have been no further changes to the repository. Repeat +from 2.1 if repository has changed.
      5. + +
    5. +Get clearance from other developers to check in your changes.
      6. + +
    6. +Check in your changed main branch.
      7. + +
    7. +Build and validate the new changes.
      8. + +
    8. +Tag code as "checkpointNN". Add records to docs/tag-index.
      9. + +
    9. +Build and validate test cases (see testing).
      10. + +
    10. +Create and install checkpointNN.tar.gz
      11. +
    + +
  3. +Testing
    4. + +
    Things in a checkpoint tree require a test case that can be used to +validate the component. +
  4. +Checkpoint tagging
    5. + +
    No code should be left in limbo (un-tagged) for extended periods. On +the other hand it's unnecessary to create a checkpoint tag for every little +change. Checkpoint tags should be made after a particularly significant +code modification or otherwise on a regular basis, say bi-weekly. Very +often we set a list of goals to be reached by the next checkpoint which +sometimes takes more than two weeks to achieve. Obviously, in this case +a bi-weekly checkpoint would not be useful. +
  5. +Release tagging
    6. + +
    Releases are only based on checkpoint tree code. Maintenance fixes +to releases are also maintained within the checkpoint tree. Files within +a release must have accompanying documentation. The form of this documentation +depends on the file type. +
  6. +Branches
    7. + +
    Branches are a useful tool for making changes prior to checkpoints +without breaking other working versions but it must be understood that +branches are short-lived and that releases and checkpoints not be made +from a branch. Branches are especially useful for adding totally +
    new features. bug-fixes to checkpoints are introduced by moving checkpoint +levels forward. The only historical code maintenance that s employed is +for fixes and patches to formal releases - not checkpoints.
+ +

+Someone checked-in broken code so not my code doesn't work?

+You have several options: +
    +
  1. +Politely email everyone at support@mitgcm.org asking what  has happened +and that it be fixed?
    2. + +
  2. +Figure out why the new code is broken, fix it, check it in and proudly +send a message to support@mitgcm.org to show how constructive you are.
    3. + +
  3. +Complain that the quality of work is too low and then do nothing to fix +the code.
    +
    4. + +
    We advise you to only use the third option if you are confident that +your own contributions to the code are bug-free, well written, documented +and fool proof.  :)
+ +

+These policies are causing me a big problem, what can I do?

+The policies are not enforced by any mechanism other than mutual agreement! +If you think the policies are not appropriate then let us know and we can +discuss changing them. However, if you simply ignore the policies regarding +the checkpoint_release trees then your code may be removed and/or your +access revoked. +

+What about bitkeeper

+We are looking at bitkeeper (www.bitkeeper.com). It looks cool, but policies +are still important. Any experience, suggestions let us know. Watch this +space! +

Questions, comments e-mail: code.czars@mitgcm.org +
+

+ + + + + + +
Last modified on $Date: 2001/02/17 17:08:40 $ +
CVS: /u/gcmpack/mitgcm.org/../cvspolicy.html,v +$Revision: 1.10 $
+
-Questions, comments e-mail: code.czars@mitgcm.org