Basic Code Development Workflow

Most changes to the Dakota source code should be made to the "devel" branch (or another local or remote topic branch).  Conceptually, the project and workflow will resemble that in the figure below, where "production releases" are simply stable states from the "devel" branch vetted and pushed to the "master" branch by a periodic automated process.  User pushes to the "master" branch are disallowed.  After creating a Dakota project as described in the previous section, the "devel" branch and associated submodules for that branch can be obtained via:

git checkout devel
git submodule update --init

If applicable, the state of the private local repository content should also be made consistent with the Dakota devel branch by doing:

./sync.local-git.sh 

At this point, you can make code changes, do local commits and push your changes to the Dakota public server. 

Commit log format: Format your commit messages as discussed here: https://git-scm.com/book/ch5-2.html#Commit-Guidelines, for reasons discussed here: http://chris.beams.io/posts/git-commit. Key guidance (editors that are GIt-aware will automate this for you):

  • Short (about 50 char) one line title that indicates which capability, bug, or topic the commit relates to, followed by a blank line
  • Body with details explaining what/why (typically how the work was done is less important), wrapped at about 72 characters
  • Include the DAK-xxxx, DAKSUP-yyyy or other issue number as Jira will auto-link it

http://nvie.com/posts/a-successful-git-branching-model/


Pushing changes to the remote repository

Pre-push testing: Before pushing to "devel," code must compile, and all RHEL7 Linux unit tests should pass and regression tests should PASS or DIFF according to the current gold standards (see dakota_assay.py).  (Other platforms need not be clean.)  If this standard is too stringent, consider using a local or remote branch.  Typically you would want to pull from the origin repo (see below) and rebuild before running tests to prevent thrash integrating with others' changes.  Some helpful shortcuts (second option being fastest, but less complete):

  1. Run all tests, then verify against expected gold standards using the assay script
cd build/test
make dakota-diffs-clean
ctest -j 4 -R dakota_
# produce dakota_*diffs.out
make dakota-diffs
# compare to expected results
source/local/scripts/dakota_assay.py \
-s source/local/snl/sqa/artifacts/release_standards/trunk/snlfull-Linux-diffs.out \
-a dakota_diffs.out
  1. Run all tests, omitting those known to DIFF (all CTest tests should PASS):
cd build/test
ctest  -j 4 -LE Diff

"Okay tests are clean, I'm ready!" When you are ready to push your changes (i.e., one or more local commits) to the remote repository, do the following steps:

  • Ensure your local devel branch is current with respect to any changes made to the remote repository since your last update.  Do this even if you updated before testing. (NOTE: a convenient alias can be defined for this command):
git pull --rebase origin devel 
## git pull --rebase origin devel --recurse-submodules=on-demand
git submodule update --init
  • Resolve any conflicts you might have with changes from the previous step.
  • Do the push:
git push

NOTE: You can do a trial run before actually doing the push by adding the --dry-run option to the previous command:

git push --dry-run

"There are test failures or DIFFs; what next?" 

  • Minor DIFFs: If the change induces DIFFS that the committer can easily review and bless through an RHEL7 build, typically resolve them, update commits as needed, and push to devel.  Even in this case, it may be helpful to create a local branch (git checkout -b bug_name_diffs) to separate that work in case resolution ends up being challenging or long-running.
  • Major DIFFs and/or need help from build system or team review/resolution: Push the named branch to origin, e.g, git push origin bug_name_diffs.  Then developers can collaborate to resolve DIFFs, and/or an automated build job can be conducted on that branch.  The software engineering infrastructure team can help with assigning developers to review and resolve differences.
  • Once resolved: Whether local or remote, when done resolving the issues and DIFFs, merge the branch into devel and push to origin.  Delete the remote (and local) branch when no longer needed.

 


For More Information

Git-based workflows:

http://nvie.com/posts/a-successful-git-branching-model/

https://www.atlassian.com/git/tutorials/comparing-workflows/centralized-workflow