Source Control What technical communicators need to know

About me

What I’ll cover NeedConceptsBest practicesSome tools

What is source control? A system for managing changes to source code

I’ve deleted a file by mistake. Someone has overwritten my changes! Before you can go on holiday, can you leave us all your files? Who changed this file? Why? Who’s got the latest version of this file? Where are the graphics files we used for this topic? I need to find the files we sent to the translators. The developers have pulled this feature. Can we undo the documentation changes?

Why don’t we use it? “I’ve made it a policy never to touch source control as I still don’t really understand how it works!”

Do you need it? Multiple authors Many small components Multiple concurrent versions Documenting software Unless...

Can you manage without it? Sole author Few components Clear process Reliable backups Instead of SC, you could...

The basics Common Repository Personal Workspace

Adding files Alice Change list Comment

Bruno Changing existing files Alice Comment Change list

AliceBruno Synchronising changes

Best practices Use comments Keep unrelated changes separate Synchronise frequently

Deleting files Alice

Reverting changes in the repository Alice

Concurrent changes and merges

Concurrent changes - example Bruno Alice

Merge example

Merging concurrent changes BrunoAlice 3

Merge with caution Not foolproof Some files don’t Different from software But...

Best practices - merging Avoid merges for some files! Minimize concurrent changes Merge little and often Consult others if necessary Check the results

Baselines

Baseline example Alice Beta

Branching Permanent Concurrent released versions Temporary New features

Branching in action Trunk Feature/Development Branch Release Branch

Best practices - branching Propagate from release branches promptly Merge to feature branches regularly

What belongs in source control? Sources Not auto- generated outputs

Choosing a tool

The choices Free or paid forHosted or self-hostedFront endCentralised or DistributedHAT integration

Some source control tools Free, CLI + limited GUI Several GUIs, SourceTree is free Git Free, CLI only Several GUIs, TortoiseSVN is free Subversion (SVN) Free for small teams, CLI only Several GUIs, SourceTree, Tortoise Hg are free Mercurial Microsoft Free for small teams, includes GUI Team Foundation Server (TFS) Free for small teams, includes GUI Perforce IBM Enterprise, not free! Rational ClearCase

© Marjorie Jones 2015 Artwork © Martin Jones 2015 E: W:

Resources There is a comprehensive list of current source control tools here: /List_of_revision_control_software To request the handout that accompanies these slides,