Introduction

In this training workshop you will learn about the fundamentals of software engineering in a research context and explore strategies and tools for collaborative development. These will include:

  • Version control and git
  • Automated testing and continuous integration
  • Contributing to open source software
  • Project management tools for small and larger projects

The training will consist of guided sessions, student presentations, and programming exercises.

Schedule

Each day consists of a morning session from 10am to 12:30 and an afternoon session from 1:30pm to 4pm.

Monday

  • Morning Session
    • Version control, collaboration and licenses
  • Afternoon Session
    • More version control, collaboration and licenses

Tuesday

  • Morning session
    • Student presentations on languages, tooling and best practice
  • Afternoon Session
    • ARC collaboration hour and social hour

Wednesday

  • Morning Session
    • Testing and continuous integration
  • Afternoon Session
    • Good-first-issue open source hackathon

Thursday

  • Morning Session
    • Project planning and discussion
  • Afternoon session
    • Project management tools and agile ways of working

Friday

  • Morning Session
    • Pair programming activity
  • Afternoon Session
    • Further pair programming with tests
    • Discussion and evaluation

Preparatory work

Before the start of this training week, you should complete the following preparatory work:

Prepare a presentation on a programming language

For the Tuesday morning, you should prepare (in groups of two) a presentation about a programming language. This should cover:

  • Areas where the language is most commonly used
  • Pros and cons of the language
  • How people typically release software written in the language (making source code available? package managers?)
  • Widely used testing frameworks
  • Code styling and linting tools
  • Other things that are considered good practice when using the language

Who is in each pair and which language they present about is up to you: you should form your group then assign yourself to one of the sub-issues in this GitHub issue. If you wish to talk about a language that is not yet included, you may add an additional sub-issue.

Complete the git pre-reading

You should complete the pre-reading about git.

git

We assume all students have installed git version 2 or newer, and have run the following commands once or twice before in their lives:

git config
git init
git status
git add
git commit

If not, please install git then spend a bit more time going over the prerequisite reading, at the end.

GitHub

We also assume all students have a GitHub account and have browsed around a repository on GitHub before (like this one!)

[!TIP] If you're creating an account for the first time, we recommend adding your university email and a personal one. You'll want your GitHub account to outlive your PhD.

Optionally, you can install the GitHub CLI you might find it easier to authenticate, and it's pretty useful to have it around when working with GitHub.

Technical setup

If you've not already done so, configure git so it:

  1. knows your name (or username);
  2. knows your email address; and
  3. is authenticated to push to GitHub.

[!TIP] You can use your real name and email address for 1 and 2, or you can use your GitHub username and anonymised GitHub "noreply" email if you're concerned about privacy.

For thing number 3 you can either use HTTPS (which GitHub recommend) or SSH. During your PhD you'll probably encounter SSH so there's no harm in doing it that way:

Example commands (click to expand)

If you've never done these setup steps before your terminal history should look something like:

git config --global user.name "Joe Bloggs"
git config --global user.email "jbexample@users.noreply.github.com"

ls ~/.ssh  # check for existing keys and ssh config, then...
ssh-keygen -t ed25519 -C "jbloggs@ucl.ac.uk"
touch ~/.ssh/config
echo """Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519""" > ~/.ssh/config
pbcopy < ~/.ssh/id_ed25519.pub  # copy your public key to the clipboard

And then you should have pasted the key into your GitHub account (Settings » SSH and GPG keys » Add new ...).

Technical setup pre-lesson check

To check you've done all of the technical prerequisite steps please run:

git --version  # should show version 2.something
git config --global --list  # should at least show user.name and user.email
ssh -T git@github.com  # should say "Hi <you>! You've successfully authenticated..."

If you installed the GitHub CLI:

gh auth status  # should show a check mark: ✓ Logged in to github.com

Reading

Yes, there's a bit of prerequisite reading!

Either:

We're going to assume you've read -- or are familiar with:

If you find one of them hard to understand, swap to the other one! If you've used git and GitHub before you should be able to skim-read these quite quickly. If you're already power-git user: please come to the session anyway and help out!