Configuration and Build Control =============================== The purpose of configuration and build control is to - allow users to run the OPS system without fear that something will change under them causing inconsistent results or outright failure, and - allow coders to update their code regularly and to test it in its full software environment without fear that they may be interfering with someone else's testing. We can meet these desires if everyone follows the rules and we communicate effectively. Communication is everyone's responsibility, but I'll provide the rules. This is not a tutorial on how to accomplish everything mentioned herein, these are just the rules, not the implementation. If you don't know how to do something, ask. 0) What is Controlled ------------------ All software, documents and reference data necessary for the SO and DA to operate that you are responsible for maintaining should be part of the version, configuration and build control described here. This may not include tools or utilities that are useful to you but are not a routine part of operations. You must use your best judgment to decide if a given piece of code should be controlled. If you have doubts, feel free to ask discuss it. Programs, libraries, scripts, etc. which will not be altered and are Developed and maintained elsewhere can reside in system directories, private bin dorectories, or in /proj/wire/bin or lib etc. and do not need to participate in the control process. The WIRE-maintained version of Perl, and various image analysis routines and libraries are examples. Anything of public value that does not need to be controlled can go in /proj/wire/bin. 1) Version Control --------------- Use a version control system religiously to keep careful track of old versions so they can be reconstructed to reproduce old results or undo the nasty effects of a buggy delivery. Many people are now using CVS. It has many advantages and takes care of many tasks for you. Everyone should learn to use it or justify why they are not and allow me to validate the system they are using. Version control should be applied to all software (scripts, perl, C, Fortran, etc.) and data which will participate in the build/delivery process. Consider doing checkpoint version control on your software regularly, e.g. every day if you're developing rapidly, or every week if things are changing more slowly. 2) Controlled Delivery ------------------- Each coordinated, controlled delivery should have a tag as a designation, such "1.2" or "1-21-99_checkpoint" or some such. The tag will be declared by whoever is calling for the delivery. When you've finished changing your code and it has passed unit testing in your private environment (I can show you how to do this) apply the delivery's tag to all your code as you check it in for version control. In CVS this is done with the "tag" command. For non-CVS users, it may mean naming a directory or tar file with the tag. If you must alter code (a late-breaking bug) you must re-apply the tag to the new code before delivery (or you must redeliver with the newly tagged code). Once your code is version controlled and tagged, here is what delivery means: . Check and, if necessary, update your delivery script (see below) to reflect all your current deliverables. . The person in charge of the build will tell you whether you're delivering to OPS, DEV, TST or something else. This is the delivery "target". The old target will disappear; NO CODE WILL BE INHERITED FROM THE OLD TARGET TO THE NEW. . Compile EVERYTHING fresh (not just stuff that's changed). . Perform any required testing (see below) to confirm the validity of the delivery. This may involve an interim delivery to DEV or TST for integration and in-situ testing. . Once they are validated, move all deliverables to the proper subdirectory in the target when asked to do so. If you're not using CVS, your delivery should include your code. . Programs must ONLY point to subprograms, libraries, sub-scripts, include files, etc. that are in THE SAME TARGET. This means that your scripts and code must have a way of changing what libraries are linked to, what include files are used, what data is read, etc. depending on the selected delivery target. . DO NOT redeliver ANYTHING to the target without getting approval from the proper source, after careful review. (See, however, uncontrolled deliveries below.) A script to do the recompilation and delivery for you will save you from many errors; WRITE ONE! Makefiles work well for this but you can use whatever is comfortable (e.g. a csh script), but you MUST have a delivery script. 3) Uncontrolled or Less Controlled Deliveries ------------------------------------------ To have a place where more rapid, less organized delivery can take place, other delivery targets will be available. E.g. DEV or TST. The general rules for these are: . Private delivery Copy a public delivery directory (such as DEV or OPS or TST) to private space for your use only and deliver your code updates here until they work. A script I've written called "duptree" can be used to perform this copy of a delivery. Duptree is not perfect and may keep everything internally consistent, but for private testing it ought to be good enough. Official SODA/SOC tests and real ops should never use code from private deliveries. . TST If a TST delivery target is available and in use you may deliver new code at will without synchronization or coordination. You risk bumping into incompatibilities as others drop new code in, but you may as well discover it here. Official SODA/SOC tests and real ops should never use code from the TST delivery. . DEV - Before S/W freeze: Is often used much like TST above, but one should exercise more self control and deliver only code which is somewhat rung out after checking around to make sure your not about to interfere with a run anyone has underway. - After S/W freeze: deliveries can be made asynchronously (i.e. everyone doesn't have to deliver everything anytime anyone wants to update some code) but you must obtain official approval before delivering. Tests and ops CAN run out of DEV but only after approval. . OPS OPS should always contain the results of a fully controlled delivery. In general, tests and real ops will run out of the OPS target. 4) Testing ------- We're weak on organized testing. Here is what SHOULD be happening: . RTB The RTB should run for every controlled delivery and periodically on DEV as a check. Both SO and DA should work toward having reasonably complete regression test baselines which exercises all critical components of the system and a fairly automatic way of validating the results. The RTB need not be burdensome; it's just a basic aliveness and integration check. . Validation Most often a full validation of a fresh, controlled delivery to DEV will preceded a delivery to OPS. An exception might be made for a small changes which will not affect most of the system, if time is pressing. Criteria for a more complete validation and testing procedure needs to be decided upon in order to feel confident in deciding code is ready for a controlled delivery to OPS and use in a test or real OPS. Glossary -------- Delivery target a directory hierarchy that looks like this: ...target/bin = executables (scripts, binaries, perl, idl, etc.) ...target/lib = binary libraries ...target/lib/include = source code include files (e.g. '.h' files) ...target/include = symbolic link to lib/include ...target/lib/perl = perl libraries ...target/doc = any documents needed by the program (e.g. on-line help) ...target/src = source archive ...target/data = any reference data which must be kept strictly sychronized with the code. (A delivery target might not have anything in 'doc' or 'src', and sometimes the 'include' symbolic link is missing.) OPS delivery target /proj/wire/ops DEV delivery target /proj/wire/dev TST delivery target /proj/wire/tst Private delivery a delivery to a target in one's private work space; something like /proj/wire/tim/dev RTB Regression Test Baseline. A suite of automated tests for doing a quick validation of a delivery.