Introduction to Versioning Version 1Version 1 Version Database file Version 3 Version 2 Version 1 Sherry Lake Data Management Consultant University of Virginia Library shLake@virginia.edu Bill Corey Data Management Consultant University of Virginia Library wtc2h@virginia.edu © 2013 by the Rector and Visitors of the University of Virginia. This work is made available under the terms of the Creative Commons Attribution-ShareAlike 4.0 International license http://creativecommons.org/licenses/by-sa/4.0/

Goals for the Workshop Identify version control problems and causes Understand differences between Version Control and Revision History Learn about programs that provide versioning Learn about GitHub an online version control repository

How do you… Identify the most recent version of a file? Go back to a previous state of the file? Tell the difference between versions of a file? Know which is the “real” final version? Keep from working on the same document at the same time? What problems occur if you can’t do these? leads to wasted time and considerable frustration both on the part of the author who spends time needlessly working on an old version and the reader who has read an obsolete document. STOP – Ask how they do “Version” control now. Do they have multiple collaborators? What has worked, what didn’t (doesn’t)?

What is Version Control? Version control refers to file revisions management. It facilitates best practice in research data management during a project where constant redrafting and revision is occurring by numerous researchers. Achieved by: Naming conventions File Revision (file history) Document Control Sheets Versioning Software Very few documents or spreadsheets are ever started, drafted, reviewed and completed by one person in one sitting. More often there will be several people involved in the process and it will occur over an extended period of time. Without proper controls this can quickly lead to confusion as to which version is the most recent. Consider the drafting of a final report by a project team. The project manager will write the first draft. They then wish to seek the input from the five other members of the team. They will often email the draft report as an attachment to the members of the team, each of whom now set about reviewing the report and adding their comments before sending it back to the author. There are now six versions of the draft report. Once all the comments in all the copies have been reviewed and implemented another version is created and perhaps re-sent for another round of review. We now have over a dozen different versions of the report in circulation and a recipe for chaos. The inability to quickly and easily identify the latest version of a piece of information can lead to an array of problems. Finally of course it leads to wasted time and considerable frustration both on the part of the author who spends time needlessly working on an old version and the reader who has read an obsolete document.

Naming Conventions Collaboration: few people Length of project: short Need training and documentations on how (use date/time/initials?) Does not prevent two people working on the “next” version (2 diff files) at the same time. Best for projects that…

Naming Conventions [yyyymmdd] [filename].[file extension] Examples: 20111218 Learning Spaces Program.doc 20111211 Learning Spaces Program.doc [filename]V[+1].[file extension] Library-RenovationV5.doc Library-RenovationV4.doc Make it easy to identify drafts and final versions at a glance This allows sorting of filenames in date order (without relying on the Modified Date which may not tally with the event or meeting date). Need to note the final version.

Software that saves versions*: Revision History Software that saves versions*: Wiki (i.e., UVa Collab) Wordpress UVa Box MS Sharepoint Google Drive Evernote (premium feature $) Features (not available on all listed above): Download previous versions Revert back to previous versions Compares 2 documents Step through drafts to visualize changes side-by-side Wiki – history of the page (https://collab.itc.virginia.edu/portal/site/37e8e322-03a1-4d40-b502-d373c53bace1) HISTORY - can compare 2 versions (some wikis allow versions to choose from – uvacollab only selected one and previous or current), and revert back to previous ones. Highlights changes (key at bottom of page) WordPress – see auto-saves and manually-saved versions (http://pages.shanti.virginia.edu/SciDaC/wp-admin/post.php?post=619&action=edit) Choose “Best Practices Workshop” – scroll down to “Revisions” – click on one, then get can compare 2 revisions UVa Box saves last 10 (click version # to get version list) https://virginia.box.com/s/euwehfx4d1r3j62ow7uv Can download any of the versions, or make current – no comparison MS SharePoint: “Version history” can restore earlier version (sharepoint does allow – check out setup Google drive: Force-saves revisions as you work (and can see these detailed revisions if want) (https://docs.google.com/document/d/1k9X4yCypgTqrdY5jECbyGy-Ji9rfkukeOAWb6cdwloM/edit) File -> See revision history compares current (clicked) and previous one – can see what changed. –can restore selected revision *List not inclusive

Document Control Sheets record details of the revision process who made the changes, when and why For more formal documentation that you know is going to be subject to several iterations of review and release, it may make sense to include a document control sheet as part of the overall document design. This can be used to record details of the revision process including who made the changes, when and why. version control table with information such as versions, dates, authors, and details of changes to the file. MS Word – putting comments and saving w/ same name….just adding comments, nothing deleted or changed.

Data Provenance Document the origin and history (transformations) of a dataset Tools for documenting data file edits: OpenRefine (formerly Google refine) Statistical software packages Key point to why version control, history is important in research: data provenance is defined to be information that helps determine the derivation history of a data product, starting from its original sources. two important features of the provenance of a data product are the ancestral data product(s) from which this data product evolved, and the process of transformation of these ancestral data product(s), possibly through workflows, that helped derive this data product. For Excel spreadsheets this would include writing down the steps taken in transforming the data, while advanced data tools (such as Open Refine, formerly Google Refine), often provide methods of exporting machine-readable data containing processing history. Any programs that have been written to process the data should be available when users access your end result and shared with your dataset. !!!!! Put google refine history files on Box in sharing folder

Version Control Systems Can function as additional backup Can go back to earlier version (or “last known good”) Can document who & what changes Work on any type of document (not just software) Online service, free (be aware of privacy policies when using hosted services) I have Described some tools that integrate version control by maintaining backups of your digital objects such that you can retrieve versions of them at any point in their creation. But full-fledged version control system does a lot more….. Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. Version control (also known as source code management or source control) is a formal system by which changes to a set of documents are tracked and managed. Used in software and web development, law, and business, version control systems provide a historical audit trail of when changes were made, who made them, and what was changed. Version control systems make it easier for multiple people to modify the same documents without stepping on each other’s toes. And even if you’re working by yourself, version control provides an easy way to back up and have multiple versions of your documents. Version control software is a reliable way to share files between machines. It also allows people to work simultaneously by tracking and managing conflicts (commit – checkout – checkin). And keeps a permanent history of what state programs, data, and documents were in at various times. (change/diff)

Version Control Systems Basic concepts: Repository Server Client Add - Commit Check in / Check out Changelog / History Diff Advanced features: branching, merging, conflict resolution Earlier version – same as revision, Version control software is a reliable way to share files between machines. It also allows people to work simultaneously by tracking and managing conflicts (commit – checkout – checkin). And keeps a permanent history of what state programs, data, and documents were in at various times. (change/diff)

Version Control Graphical View Here’s a way to look at a Version Control system (simply): Local working copy, process of checking in and checking out files…. http://pages.cs.wisc.edu/~driscoll/software/vcs/

Distributed Version Control http://pages.cs.wisc.edu/~driscoll/software/vcs/

Version Control Software Examples: Subversion (SVN) a local server tortoiseSVN: windows client software github.com: online repository (server) git: client software Git – decentralized approach, can still use many of the Version Control features w/o having to install extra software (client AND server). Github is a distributed VCS, Subersion is a vcs – one repo (local)

github Exercise Create github.com account Create a repository online Create a repository locally Add a file and Commit If there is time – at least 15min. Create username (email) and password Select your plan $0 – Click “Finish sign up” Welcome screen – Create a repository (all repositories in Free version, must be public– open) Give it a name & description, Click “Create Repository” Follow these steps from this site: https://help.github.com/articles/create-a-repo Used git commands that git.hub displayed to create a local repo and then pushed it to the online repo (needs username or password) Then can see repo set up on github

More Information UVa Box http://its.virginia.edu/box/ MS Sharepoint (UVa) http://its.virginia.edu/sharepoint/ Github.com Github help https://help.github.com/articles/create-a-repo