Version Control

Source code for GMAT is managed using the distributed version control system (DVCS) Git. Git provides a hierarchic approach to code management that lets developers build and test their code updates without pushing their changes to the full development community. This approach lets developers share code changes with each other without affecting all of the development team, allows for the review and testing of code updates before pushing them to the team, and lets the full team review and test delivered code before pushing it to the release repositories. This page provides an overview of the repository management scheme. Specific tasks you may need to perform in Git are described on the pages found in the links referenced from this page.

The GMAT Repository

Figure 1 shows the general layout of GMAT's repository structure. Ongoing GMAT development is made to the code in the repository Trunk. From time to time, Trunk is branched to experiment with specific new features and capabilities that could have significant side effects on the core system code. Development on these branches proceeds in parallel with core code development. If the new development produces a feature that the project wants to incorporate into core GMAT code, that branch is merged back into trunk. (As an example, this process was followed when the orbit determination capabilities were developed.)

 Figure 1: Repository Structure

Occasionally a branch is made that does not produce code that needs to be incorporated into the core code. These branches are left in repository (and may be moved into a subfolder) even when work on them ceases.  When a version of GMAT is released, the code for that release is tagged with the release version number, and the code is branched so that any issues found in the release can be addressed separately from ongoing development. If a code change in this maintenance branch needs to be incorporated into core development, that code is merged back into the trunk code.

The Git Repository Workflow at GSFC

The Git DVCS provide flexibility by managing a complete copy of the repository on each user's computer. Updates from other users are brought into the repository by pulling the changes from one repository into another. Local changes are pushed to the repository/repositories that need(s) them. Procedures followed by team members described on the Common Git Tasks page.

A core feature of Git is that each user of the repository has a local copy of the repository. As the user makes changes, the changes are committed locally in order to maintain the code, but those changes are not yet available to other users of the system. This feature lets each user make small changes that can be discarded if necessary on the local clone of the repository without affecting the other members of the team. When a user is ready to share the resulting changes, they are pushed to a more central copy of the repository so that other team members can use the updated code. The rest of the team members then pull the changes to their local repositories, picking up the updates for their use.

Figure 2 shows the cloning structure for work performed at GSFC by the development team. Each developer clones the GMAT repository and works in the clone. This work includes making local commits as needed in order to preserve midpoints in feature development or other ongoing work. As other developers commit code, those changes are pulled into the developer's repository to ensure that the local code base is synchronized with the GSFC repository. When the developer determines that updated code is ready for incorporation into the main repository, the developer pushes those changes to the GSFC repository.

Figure 2: Repository Work Flow at GSFC

The daily build system updates code from the GSFC repository and uses that code to build the executable used for nightly and weekly test runs. The Test repository used for this process pulls code from the GSFC repository, but does not push changes back to the main repository.

The branching configuration includes updates to GMAT's open source Subversion project at SourceForge. The SVN repository at SourceForge was cloned to create the Git repository behind the GSFC firewall when this workflow was configured. That clone, called "GMAT at GSFC" in the figure, is used for GMAT development activities. Developers on the core GMAT team at Goddard push and pull changes directly from the GSFC repository. Code updates are pushed to the Subversion repository periodically to keep the publicly visible code synchronized with ongoing development. This action happens at least with each public release of the software, and may happen at intermediate points in the development cycle as well. Details about the procedures used to manage the SourceForge/Git communications are covered on the Administrative Git Tasks page.

Work Flow for Contractors

Figure 3 uses the repository structure used at Thinking Systems as an example of the repository work flow performed by contractors on the GMAT team. Work performed at Thinking Systems (and at other contractors) mirrors the approach followed at GSFC, with an added wrinkle to manage changes made off site. The development repository at GSFC is cloned to a local repository, labeled TSI Work in the figure. This pull process is exercised on a regular schedule to keep the contractor's code base synchronized with the repository at GSFC. Developers at the contractor's site interact with this company clone when working on features for the system, following the same procedures as are used by developers at GSFC.

Figure 3: Repository Structures at GSFC and Thinking Systems

The contractor's working repository never pushes changes directly back to the GSFC repository. When changes are ready for delivery, they are committed to the Thinking Systems code review repository. After review and testing, those changes are pushed to the GSFC repository and then pulled back to the Thinking Systems master repository. This added intermediate repository plays testing system the role at the contractor's site. Code is checked to ensure that it is of high quality and matches the system coding standards before delivery to GSFC. An executable is built from the code, and checked against a subset of the GMAT regression test suite to ensure that the code changes do not adversely affect the system code. Once the code is ready for delivery, it is pushed to the GSFC repository.