Me:

1. Me: Dr James Hetherington -- UCL Research Software Development Team -- @uclrcsoftdev -- blogs.ucl.ac.uk/research-software-development/ -- www.mailinglists.ucl.ac.uk/mailman/listinfo/research-programming

2. Version Control and Issue Tracking • Managing code inventory • “When did I introduce this bug?” • Undoing mistakes • Working with other programmers • How can I merge my work with Jim’s? • What’s the most important bug to fix next?

3. What is version control? (Solo version) • Do some programming • > my_vcs commit • Program some more • Realise mistake • > my_vcs rollback • Mistake is undone Syntax here is example only!

4. What is version control? (team version) Sue Jim • Create some code • > my_vcs commit • …wait… • …wait… • …wait… • …wait… • >my_vcs update • Do some programming • … program some more • > my_vcs commit • Oh Noes! Error message! • > my_vcs update • > my_vcs merge • > my_vcs commit • More programming… • … wait … • … wait … • Join the team • > my_vcs checkout • do some programming • > my_vcs commit • Do some programming • … more programming… • > my_vcs commit • … more programming … • … more programming … • … more programming … • … more programming … • … more programming … • > my_vcs commit • Error again…

5. Centralised VCS concepts • There is one, linear history of changes on the server or repository • Each revision has a unique identifier • You have a working copy • You update the working copy to match the state of the repository • You commit your changes to the repository • If you someone else has changed it you have to resolve conflicts between your changes and the repository, and then commit

6. Centralised VCS

7. Centralised VCS solo workflow Commands for this in Subversion: svn checkout http://mysvn.ucl.ac.uk/mycode vim myfile.py svn commit touch mynewfile.yml svn add mynewfile.yml vim mynewfile.yml svn commit Time

8. Centralised VCS Team workflow: no conflicts Jim’s commands: svn checkout http://…ac.uk/ourcode vim jimfile.py svn commit Sue’s commands: svn co http://mysvn.ucl.ac.uk/ourcode svn update cat jimfile.py # Sue can see changes vim suefile.py svn commit

9. Centralised VCS with conflicts Jim’s commands: svnupdate vim sharedfile.py svn commit Sue’s commands: svnup vim sharedfile.py svn commit svn: Out of date: ’sharedfile.py’ svn up vim sharedfile.py svn ci

10. Resolving conflicts On update, you get a prompt like: > svnupdate Conflict discovered in ’sharedfile.py'. Select: (p) postpone, (df) diff-full, (e) edit, (mc) mine-conflict, (tc) theirs-conflict, (s) show all options: If you choose (e) or (p) the conflicted file will look something like: > cat sharedfile.py previous content <<<<<<< .mine Sue’s content ======= Jim’s content >>>>>>> .r4 Previous content You edit to fix this, then save.

11. Revisiting history • You can update to a particular revision • svn up -r 3 • You can see the differences between your working area and a revision • svn diff (to current repository most recent version) • svn diff –r 3 • You can see which files you’ve changed or added • svn status • You can get rid of changes to a file • svn revert myfile.py

12. Distributed and Centralized Version Control • Centralized: • Some server contains the remote version • Your computer has your copy • To switch back to an old copy you need the internet • E.g. cvs, subversion (svn) • Distributed: • Every user has a version of the full history • Users can synchronize their history with each other • Having a central “master” copy is a policy option • Most groups do this • E.g. git, mercurial (hg), bazaar (bzr)

13. Distributed VCS In principle: In practice:

14. Pragmatic distributed VCS • Subversion • svn checkout http://mysvn.ucl.ac.uk/mycode • svncommit • svn up • svn status • svn diff Git git clone git@github.com:ucl/mycode.git git commit -a git push git pull git status git diff

15. Why go distributed? • Easy to start a repository (no server needed) • Easy to start a server • Can work without an internet connection • Better merges • Easy branching • More widespread support Why not go distributed? • More complex commands • Easier to get confused!

16. Distributed VCS concepts (1) • Each revision has a parent that it is based on • These revisions form a graph • The most recent in each copy is the head or tip • Each revision has a globally unique hash-code • E.g. in Sue’s copy revision 43 is ab3578d6 • Jim thinks that is revision 38 • When you bring in information from a remote the histories might conflict • Histories from different copies are merged together

17. Distributed VCS concepts (2) • You have a working copy • You pick a subset of the files in your working copy to add to the next commit: these go into the staging area or index • When you commit, you commit: • from the staging area • to the local repository • You push to remote repositories to share or publish your changes • You pull or fetch to bring in from a remote

19. Distributed VCS solo workflow Commands for this in Git: Create a file myfile1.py gitinit git add . git commit create a new file myfile2.py and edit myfile1.py git add file2.py git commit Only changes to file2 get into commit Edit both files git commit -a

20. Distributed VCS solo with publishing Commands for this in Git: gitclone git@github.com:ucl/mycode.git Edit a few files git add --update git commit git push Edit a few files git commit -a git push

21. Distributed VCS Team workflow: no conflicts Jim’s commands: gitinit git add mycode git commit git remote add --track master origin git@github.com:ucl/foo.git git push git fetch git merge git commit –a git push Sue’s commands: git clone git@github.com:ucl.foo.git git commit –a git push git pull

22. Distributed team workflow with conflicts Jim’s commands: git commit -a git push Error: ! [rejected] git pull git commit –a git push Sue’s commands: git commit –a git push git commit –a git push git commit -a git commit –a git pull

23. Really distributed: more than one remote git remote add sue ssh://sue.ucl.ac.uk/somerepo add a second remote gitremote list available remotes gitpush sue git push origin push to a specific remote

24. Working with branches

25. Working with branches in git > git branch * master > git branch experiment > git branch * master experiment > git checkout experiment > gitbranch master * experiment

26. Sharing branches in git gitpush origin experiment publish the branch to remote git push -u origin experiment publish the branch to remote(first time) gitbranch -r discover branches on remote(s) gitcheckout origin/experiment get a new branch from a remote

27. Merging and deleting branches git checkout master switch back to master branch git merge experiment take all the changes from experiment into master exactly like merging someone else’s work git branch -d experiment the experiment is done, get rid of local branch git push --delete experiment git rid of the branch on the remote

28. Working with branches • You should have a development branch and a stable branch • You should create temporary branches for experimental changes • If you release code to others, you should make a release branch • Then you can make fixes to bugs they find • And control which of your work goes in the release

30. Tagging • You should tag working versions • You should produce real science only with specific tagged versions, and note which one

31. Tagging git tag –a v1.3 add a tag, labelling last commit git tag –a v1.3 ab48dc tag an old commit gitpush --tags publish the tags to origin

32. Branching and tagging in subversion • You can do branches and tags in subversion too • But it’s harder • svndoesn’t have real branches or tags, instead you make copies of code inside the repo • and you can merge between the copies • It works, but it’s cleaner in git • see subversion references if you need this

33. More comparisons Subversion svn up –r54 myfile.py svn revert myfile.py svn revert –depth=infinity . Git git checkout –r ab39d myfile.py git checkout myfile.py git reset –hard But git can do more, e.g.: git reset HEAD^ will undo the last commit from your local repository (providing you haven’t pushed) Both git and svn have many options – have a look on the web! http://gitref.orghttp://git-scm.com/book http://svnbook.red-bean.com/

34. Other version control systems • vcs • Really old! • Works by “locking” files instead of resolving conflicts • cvs • Very like svn • hg • “mercurial” • Very like git

35. Hosting a server • In git, any repository can be a remote for pulls • Just use • git pull ssh://theircomputer/theirrepo • There are problems with pushing to someone else’s working repo: don’t! • You can, however, create a git repo with • gitinit--bare • This bare repo has no working directory, • use it as a remote for push and pull via ssh:// • In subversion, the procedure is more complicated • You have to configure a server ‘daemon’

36. Hosting a server in the cloud • There are many services which allow you to create git, mercurial, and subversion repositories online • Typically free for open source • Typically a fee for private repositories • I recommend GitHub • Create an account at https://github.com/ • Students can get five free private repositories at • https://github.com/edu • Can interact with GitHub repositories as either svn or git • Bitbucket is also good

37. Working with GitHub

38. Set up ssh keys

39. Create repository

40. Social coding

43. Browse changes

44. Browse changes

45. Comment on and discuss code

46. Issue tracking • Your code has bugs (defects) • Your code has things you want to do (enhancements) • The best way to keep track of all this is with an issue tracker

47. Issue tracking

48. Anatomy of an issue • Type • Defect, enhancement, task • Severity • Critical, blocker, major, minor, trivial • Owner • Status • Open, fixed, duplicate, blocked, under review, won’t fix, invalid, new… • Estimated time and time spent? • Tags

49. Timeline of an issue

50. Some questions • Public or private issues • Organising issues into milestones • Estimate effort? • Who can close an issue? • Review processes • Integration with version control