Source Control

What technical communicators need to know

About me

What I’ll cover

NeedConceptsBest practices

Some 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

authorFew

componentsClear

process

Reliable backups

Instead of SC, you could . . .

The basics

• CommonRepository

• PersonalWorkspace

Adding files

A1

B1

C1

Alice

Change list

Comment

A1B1

C1

Bruno

Changing existing files

A1

B1

C1

Alice

A1B1

C1

A1B1

C1A2

C2

CommentComment C2D1

D1

A2

Change list

Alice

C1

A1A2

D1

Bruno

Synchronising changes

A1

B1

C1

B1

A2

C2

D1

A2

C2B1

D1

C2

Best practices

Use comments

Keep unrelated changes separate

Synchronise frequently

C2

A3B4

Deleting files

A3A1 A2

B2B1 B3 B4

C2C1

D2D1 D3

Alice

D3

A3A4(A2)

Reverting changes in the repository

B4

A3A1 A2

B2B1 B3 B4

C2C1

D2D1 D3

Alice

D3D4

A4(A2)

B5(B1)

C4(C2)

D5(D1)

B5(B1) C4

(C2) D5(D1)

Concurrent changes and merges

A3

D4

Concurrent changes - example

Bruno

A1 A2

B2B1 B3 B4

C2C1

D2D1 D3

D4

B4

A3

D4

B4

A3 A4

A4

!

Alice

Merge example

A3

D4

Merging concurrent changes

Bruno

Alice

A1 A2

B2B1 B3 B4

C2C1

D2D1 D3

D4

B4

D4

B4

A3 A4

3A4

!A3

A5

A4

A5

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

A3

Baseline example

A3A1 A2

B2B1 B3 B4

C2C1

D2D1 D3

D4

B4

Alice

D3

A2

D1

C2B1

Beta

BetaBeta

Branching

Concurrent released versions

• Permanent

New features • Temporary

Branching in action

D1C1B1

D1C1B1

D1C1B1

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 for

Hosted or self-hosted

Front end

Centralised or Distributed

HAT integration

Some source control tools• Free, CLI + limited GUI• Several GUIs, SourceTree is freeGit

• Free, CLI only• Several GUIs, TortoiseSVN is freeSubversion (SVN)

• Free for small teams, CLI only• Several GUIs, SourceTree, Tortoise Hg are freeMercurial

• Microsoft• Free for small teams, includes GUI

Team Foundation Server (TFS)

• Free for small teams, includes GUIPerforce

• IBM• Enterprise, not free!

RationalClearCase

© Marjorie Jones 2015Artwork © Martin Jones 2015

E: titch990@outlook.comTw: @titch990W: https://nfasa.wordpress.com/

Resources

There is a comprehensive list of current source control tools here:https://en.wikipedia.org/wiki/List_of_revision_control_software

To request the handout that accompanies these slides, email titch990@outlook.com