Follow this link to skip to the main content

CLARAty Policy for Repository Changes

by Issa Nesnas and Dan Gaines

Development Model

Before making any changes to the CLARAty repository both developers and users must read the current CLARAty policy regarding development and making changes to the repository. These policies will be updated as necessary to continue to improve our development process.

Figure 1: The Mainline Model (from L. Wingerd and C. Seiwald, "High-level Best Practices
in Software Configuration Management", Perforce Software

CLARAty uses the "mainline" development model shown in Figure 1. The "mainline," or "main" is the branch of a codeline that evolves forever. "Main" provides the ultimate destination for almost all changes which include bug fixes and new features. Release codelines and some development codelines are branched off the "main" trunk. Stable changes are merged back into the "main" trunk. The adverse to this approach is the "promotion" development model which requires the development team to move to a new development codeline after each major release.  Here are more details on the pros and cons for each approach.

Who can Commit Changes

Only CLARAty developers listed here can commit changes to the repository. Former developers, collaborators, and users need to coordinate with a CLARAty developer before committing their changes to the repository. The following modules will be exempt from this policy:

  • All modules of the form user_<username>
  • All modules of the form project_<project name>
  • New modules created for an adaptation that is funded outside of CLARAty task and has been approved as exempt

Non-CLARAty developers can check whether the modules they are working on are exempt by sending email to: claraty-help@robotics.jpl.nasa.gov. Exempt modules will not be part of the CLARAty nightly build. For a list of core module, click here (link to nightly build YAM.config).

Policy for Branching

This is intended to clarify our policy regarding codelines and branches. This is only relevant for CLARAty developers.

  • Future deliveries of software for validation will be made on branches (for deliveries made after March 1, 2005)
  • Major milestones including year-end milestones will be made on branches
  • Major developments and new features may be implemented on a branch
  • Multiple developers working on a delivery or milestone will work on the same branch
  • Branches should be delayed as much as possible
  • Branch names should use the following format: delivery_<yr>_<month>_<name> or milestone_<yr>_<month>_<name>. For example: delivery_2004_03_visual_tracking, milestone_2004_09_instrument_placement, feature_2005_02_remove_impls, and so on.
  • When branching you must move the module and all its dependencies to that branch
  • Each branch will have a lead and he/she:
    • Will decide when is the best time to branch
    • Will be responsible for merging changes back onto the main branch
    • May choose to set a different policy for software tests and commits to their branch. The default will be the "main" branch policy below
    • Will inform the development team of his/her plan prior to making the branch by sending email to: claraty-dev@robotics.jpl.nasa.gov. This will inform others who may be planning upcoming check-ins that are relevant to their planned branch
  • All other uses and developments will be on the main branch

Policy for Committing Changes to "Main" Branch

For CLARAty developers:

  • If your changes constitute a re-design of existing classes, you will need to have a team review of these changes. Send your proposal/redesign to: claraty-dev@robotics.jpl.nasa.gov and allow one week for a response. If this is a major redesign, the task manager will organize a review (formal or informal) for this change.
  • If the changes alter a generic API or alter existing behavior of a current module, you need to inform the development team of this change prior to checking in the changes. The team can assess the impact to their current work. In an email include:
    • In the title: Behavior Change - <module name>
    • A clear description of the change
    • The rationale for the change
    • Both original and modified code segments
    • Send to: claraty-dev@robotics.jpl.nasa.gov
    • Give at least 2 days for people to respond. If you do not hear back, assume that the changes are acceptable.
    • The text you type can go into the description of the cvs commit.
  • If the changes you make are for adding features or bug fixes, you can send the email after the changes are committed.
  • Err on the side of sending more emails than less. Only CLARAty developers are on the claraty-dev mailing list.
  • Document all new features and changes you make to the code.
  • Always provide sufficient detail in the Readme of the modules. Add major features to the Readme file in that module
  • All new features must be accompanied with test code to exercise the new feature. If a test was not submitted, the individual who discovers that should submit this as a bug into bug/feature tracking system. When the automated test fails to catch a bug, write a test case to capture such future occurrences.
  • If someone's commit breaks the nightly build system, it is the responsibility of that person to fix or back out their changes. Fixing a broken check-in will take the highest priority among tasks assigned to individuals.

Future Additions

  • Implement an automated build and regression tests for all targets; once this succeeds for a module, it will be tagged as tested (results from the nightly build after passing automated test. Additional tag hw-tested after tested on relevant platform. (format for regression test programs)
  • Have a system that tracks packages changes.
  • Implement release process for individual modules:
    • Prevent the release of a module in your sandbox that depends on other modules that you have modified. To release a module, you have to start releasing from the top of the dependency tree. System produces an ordered list of modules that need to be released. Future addition: allow release of a module without requiring the release of modules that depend on it. The system will build against the proper modules from original checkout. Currently this is done with tags.
    • Distinguish between tags for: released, and tested
      • Release modules with source code only. Release process should include at least:
        • Tagging CVS repository
        • Capturing module dependency and updating the database