A version control system for VIC and DHSMV (and other scientific source code development)

1. VIC DHSVM A version control system for VIC and DHSMV(and other scientific source code development) Joe Hamman Bart Nijssen, Ted Bohn, and Ning Sun May 8, 2013

2. VIC DHSVM Outline Motivation Quick Git Review The development workflow Implementation for VIC Git Management

3. Objectives… • Collaborate on and between projects, • develop in parallel (inside and outside the group), • base ongoing development off current code version, • track changes in source code over time and by user, • distinguish between new features and bug fixes, • control permissions as new features are added, • provide a platform for code review and discussion • and do it all with low overhead.

4. What is git? Git is a distributed revision control and source code management (SCM) system with an emphasis on speed.

5. Have a branch that always contains only what goes to production, another that you merge work into for testing, and several smaller ones for day to day work. MASTER Role-Based Codelines DEVELOP FEATURES

6. MASTER Frictionless Context Switching DEVELOP Create a branch to try out an idea, commit a few times, switch back to where you branched from, apply a patch, switch back to where you are experimenting, and merge it in. FEATURES

7. MASTER Feature Based Workflow DEVELOP Create new branches for each new feature you're working on so you can seamlessly switch back and forth between them, then delete each branch when that feature gets merged into your main line. FEATURES

8. MASTER Disposable Experimentation DEVELOP Create a branch to experiment in, realize it's not going to work, and just delete it - abandoning the work—with nobody else ever seeing it (even if you've pushed other branches in the meantime). FEATURES

9. The Workflow • Figures and content based on Vincent Driessen’s blog post: http://nvie.com/posts/a-successful-git-branching-model/ • Supported by Git add-on - gitflow: https://github.com/nvie/gitflow

10. Decentralized but centralized

11. The main branches Develop Branch: Working version of code (i.e. VIC 4.1.2+) Master Branch: Public Release (i.e. VIC 4.1.2)

12. Supporting branches

13. Feature branches Develop Branch: Working version of code (i.e. VIC 4.1.2+) Feature Branches: New features and experiments, may or may not be complete or functional.

14. Hotfix branches Hotfix Branch: Branches from master and updates develop and master branches (i.e. VIC 4.1.2.g)

15. Workflow • Admin controls branches: • Master • Develop • Hotfix • Release • Feature branches: • Developed offline of central repository • May contain proprietary research (pre-publish) • May be continually rebased on most recent version of develop branch • Send pull request to admin for feature incorporation.

16. Git Management Application • Web-based hosting service for projects using Git • Features: • Wiki • Issue Tracker: bug tracking and feature requests tied to commits • Code Review: Living discussions about code • Team permissions: Read-only, read-write, and admin-level access. • Easy Forking and Merging • Social Networking • Pastebin

17. For Model Users:A short tutorial on how to get source code • From Github (https://github.com/UW-Hydro) • Download current master branch zipfile • Download a previous tag zipfile • Clone the full repository • From the VIC/DHSVM website • Download the current or previous release versions

18. For Model Developers:A short tutorial on how work with github • https://github.com/UW-Hydro • Fork VIC • Pull to local machine • (git clone https://github.com/jhamman/VIC.git) • Make a feature branch • (git checkout –b feature/example) • Make changes • Push feature branch to Github fork • (git push origin feature/example) • Submit pull request

19. References: • Git: • http://git-scm.com/about • Git-Flow: • https://github.com/nvie/gitflow • http://nvie.com/posts/a-successful-git-branching-model/ • http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/ • Github: • https://github.com/features/projects