The-turing-way: Write and review version control chapter

[r-j-arnold]

Detailed description

Write a chapter for the book on version control. This will need to include an explanation of Git and Github. Experience from this issue will likely be used to assist with issue #52 and #53.

Issue progress

• [x] Collect pre-written material
• [x] Shape material into a coherent structure
• [x] Write up a neat chapter
• [x] Get reviews on the chapter
• [x] Edit the chapter following reviews
• [x] Merge to master

This chapter is being reviewed on pull request #88 to be merged into master.

[alexmorley]

Hey, so I have an idea for this which would require a little work, but based off of a few conversations with people who teach git to a wide audience I think it could work well.

The tricky thing about teaching version control is that it's quite hard to persuade people that it's worth investing in it. One idea to overcome this is to find a scenario that everyone can relate to, go through the process and find the pain points. Then suggest solutions to the pain points at a high level. Then we can show exactly how these high level solutions relate to the tools that we are suggesting.

So concretely we could have something that flows roughly like this: for each one showing how version control can help.

LMK what you think :sweat_smile:

---

You are writing an article: What do you do when...?

... you accidentally delete/lose the file you were working on.

... you want to make changes that you are not sure you will keep. Or
... you want to go back to a previous version.

... you collaborator makes a bunch of changes and you want to decide which ones to keep.

... you want to spread your work across multiple files, but track which is part of which version.

What is (branching) version control?

[Use your awesome diagrams and explanations of branching models here]

How can we use this to solve all of the problems we had above?

[Again you can use the explanations you've already done, but just add a little context to how they could solve the simple problems that everyone runs into daily]

Finally, what are a few of the pain points of using git on the terminal

• (e.g. no-one likes emailing git repos to each other, sharing issues with mutliple people etc.)
  ... Enter Github :smile: ...

[alexmorley]

Also in the @KirstieJane -chapter-model this could maybe be two chapters. But I don't think that matters too much.

[LouiseABowler]

I agree; starting with examples that people can relate to will really get across why version control is a skill that's worth the time investment.

That approach is also good if we want to work up in terms of complexity - we can start off with an example that just uses master to avoid losing work, then show how branches are useful for working on separate aspects of projects and finally work up to a full collaborative branching model.

[r-j-arnold]

@alexmorley @LouiseABowler I like this idea, making the chapter all about solutions. As you say it can be hard to convince people the learning curve is worth it, and this could help

[pherterich]

@r-j-arnold do you want comments here or on the PR? It's fairly abstract so I do it here to start with.
I was wondering if version control could be explained more basic with e.g. Word and the back button & track changes and then saving versions like this http://phdcomics.com/comics/archive_print.php?comicid=1531
But then I also get that our audience might be avoiding word - not sure which other system is wide spread and has a similar functionality that's as easy to translate. But that was how version control made sense to me and then based on that git just provides a very powerful way to do this.
I still think starting with basics and just good file naming would be really good though I guess we will pick that up when talking documentation in other chapters, too.

[r-j-arnold]

@pherterich I don't really mind where comments, are maybe carry on with them here so they're all in the same place.

Instead of word files how about .txt files? They're closer code code, and even non-coders should be aware of them.

Good file names seems a little outside the scope of version control, but you're right that should absolutely be mentioned somewhere, either in a documentation chapter or in some general "Good style" chapter.

[LouiseABowler]

I've just had a read of what you've got so far @r-j-arnold; it's looking good! One comment on the intro sections - they're good about justifying why someone should start using version control, but don't go into much detail about why it's useful from a reproducibility perspective. Could you add something on that topic, maybe about linking papers with specific versions of code?

I also came across Pro Git a couple of months back; I'll drop the link here as it might be a good resource to link out to for more detailed descriptions of git commands.

[r-j-arnold]

@LouiseABowler Good point. The intro sections aren't done yet, but you're right I need to add some more material on that. Pro Git is great and I've been using it a lot. I've just added it to the recommended reading section since it has far more in depth discussions than we have space for here.

[r-j-arnold]

This chapter is ready for review and I've removed the WIP tag from the pull request. No doubt as people contribute to this repo the chapter will improve and grow, but I think as a base version it's ready for master (pending review of course).

[alexmorley]

https://rachelcarmena.github.io/2018/12/12/how-to-teach-git.html just posting this because I think the diagrams are beautiful and might be useful to link to or borrow ideas from.

[r-j-arnold]

Done, and in master, closing issue