Learn Git / StateMod Code Example
This lesson focuses on using Git and GitHub to manage StateMod code. Complete the lesson by reading the information on this page and following links to other information. Then apply what you have learned in your work. The same concepts can be applied to other software, with variation in the development environment based on technologies.
Estimated completion time: 60 minutes
The remainder of this page discusses how to use Git/GitHub to manage the StateMod code.
- StateMod Code Version Control Considerations
- Git Workflow for StateMod Code
- cdss-app-statemod-fortran - StateMod code repository discussed below
StateMod Code Version Control Considerations
- StateMod code repository - The Open Water Foundation has migrated CDSS software to a Git/GitHub repository
(cdss-app-statemod-fortran) and confirmed compilation with
- Developer documentation - StateMod development documentation exists in a MkDocs project in the
doc-dev-mkdocs-projectfolder in the main repository. Edit and view this documentation using MkDocs protocols. For example, see the Open Water Foundation / Learn MkDocs documentation.
- Develoment Environment - Although the above environment and documentation include Eclipse/Photran,
initial work with the StateMod code used command-line compiling with the
makefile, rather than compiling from Eclipse/Photran. This simplified approach is likely more consistent with previous developer approach using a text editor to edit code. It is recommended that a simple approach be used initially and then phase in Eclipse/Photran as appropriate. Getting over the training hump for Git/GitHub should be the first priority. Also, care needs to be taken to not use Eclipse automated code formatting and change every code file.
- Standards for code indentation - An issue with collaborative software development is that each developer can
use their own code format preferences.
An important consideration is whether tabs or spaces are used for indentation.
Tabs may on the surface simplify coding; however, they complicate collaboration because different developers may use different tab-width
configuration in text editors and may try to correct the formatting introduced by other developers.
Ray Bennett (original StateMod developer) indicates that he uses tabs with 2-character width in UltraEdit editor.
An inspection of the StateMod code indicates that tabs are mainly used for comments and most source code lines use spaces.
Possible standards to implement include:
- In general, require that source code uses spaces instead of tabs, and define the tab=NSpace standard. Spaces make sense for languages that don't use indentation in their specification.
- In cases where the language uses tab indentation more directly (e.g., Python), select a standard for tab-indentation that is consistent with industry best practices. Java and Python language specification recommends 4-space tabs and this is a good general standard. If a code module has many depth levels that cannot accomodate 4-space tabs, it is a sign that the code module might be too complex and should be refactored.
- Require that developers configure their text editors to replace tabs (as typed by developer) into spaces (as inserted into file by editor software). This may require a script to run the editor as per CDSS configuration conventions, so that the developer can use other conventions on other projects.
- Provide a custom script to check for tabs in code so developers can correct.
git diff --checkto help detect format issues.
- Use git hooks to implement checks for formatting For example, run a Git Bash script when a commit is requested and if formatting issues exist.
- Support for Lahey and
gfortranCompilers - The
makefilehas been created to support both compilers but StateMod developers need to collaborate to confirm. At the moment, some source files are different between Windows and Linux and are handled by the makefile but it may be possible to use one source file and handle operating system differences at runtime (e.g., for path separator character). Ideally
gfortrancan be used for CDSS going forward.
- Support for Windows and Linux - The
makefilehas been created to support both operating systems but StateMod developers need to collaborate to confirm.
- Support for 32 and 64-bit Windows - The
makefilehas been created to support 32- and 64-bit Windows but StateMod developers need to collaborate to confirm.
- Software Validation - Because the OpenCDSS effort is migrating to
gfortrancompiler, it is necessary to ensure that the
gfortranresults match the Lahey results. This should also be the focus of initial development. The Open Water Foundation is working on a test repository to facilitate automated testing and comparison, which can be used parallel to the software code repository. A separate effort is attempting to manage StateCU and StateMod datasets in Git/GitHub and would allow an integrated process for automated testing. More information on testing will be added to development documentation and this documentation.
Git Workflow for StateMod Code
The Git workflow for a StateMod model source code is similar to other workflows. Refer to previous training lessons for instruction on how to use Git commands. The following workflow can be understood best through first-hand experience.
- Add an issue in the code repository using the GitHub Issues tool, for example to address a software bug or enhancement.
- Start on the
masterbranch in working files.
- Pull the
masterbranch from the remote GitHub repository to ensure that the starting point is consistent with work that others have done.
- Create a branch for the issue using the issue number in the branch name, for example,
- Checkout the new branch so that the working files correspond to the branch.
- Make changes to data set working files.
- Review and validate changes using automated tests and visual inspection. Need to implement standard automated tests.
- Add working files to staging and commit to the branch.
- Checkout the
masterbranch. Do a pull to synchronize remote changes that have occurred since the local branch.
- Merge the local branch using
git merge --no-ff branchname. Deal with merge conflicts if necessary. Validate the version again if remote commits had to be merged.
- Push the
masterbranch to the remote GitHub repository so that others can see the changes.
- Delete the local branch since no longer needed.
- Package the software executable, documentation, etc. and distribute/deploy as per the product protocols. For example, place the StateMod executable and documentation on the CDSS website.