Foreword#
This website describes a curriculum for a short course on Version Control and Collaborative Development for Research Software. The content has been designed specifically for the instructors (‘train the trainers’) and not for the learners. A derivative document suited to learners would require adapted design, format and distribution.
Why do we need a new course on version control?#
To any educator reading this, it will be evident that having new topics to teach is not the only reason for designing new teaching materials.
Changes in learning objectives, the target audience, or the teaching approaches are also valid reasons to
design and develop new teaching materials.
Therefore, we could answer the question: why do we need a new course about version control with Git? by simply stating:
This course has different learning objectives and teaching approaches.
However, more curious readers would like to know in which ways it is different. Which objectives and teaching approaches are different? How do these materials compare to the ones by author ‘A’ or organisation ‘O’? Which topics are different? And how different are they? Are these materials better than those in course ‘C’? Proving scientific evidence of the differences in this course will require spending considerable time dissecting, analysing and comparing with courses covering similar topics. We have chosen not to engage in that endeavour; instead, we have decided to put our efforts to better use and focus on improving how version control and collaborative development are taught to researchers in technical universities.
Therefore, we do not provide answers to the questions listed above. Though we do not mean to discourage anyone, who wishes to put the effort into finding answers from pursuing so. Instead, we explain our motivation for developing this course and hope it will satisfy readers who share our motivation. We encourage them to adopt, adapt and reuse the contents of this course.
Motivation#
After teaching introductory courses on version control using Git at the Delft University of Technology, recurring feedback provided by participants, mainly early-career researchers such as PhD candidates and post-docs, made evident that such courses were highly appreciated and interesting. However, participants also often mentioned that after the courses, they did not feel confident applying what was learned to their research. They did not know how they could apply the recently acquired skills to their research projects, even when such projects involve writing code for themselves or their research groups.
On the other hand, during my role as a research software engineer, I often find myself explaining to early-career and well-established researchers how to adopt and adapt practices prevalent in collaborative software development into their work and the work of their research groups. That meant I could spend less time contributing directly to developing their research software. In more than one case, the benefits of changing how researchers approach research software development were evident. However, in those cases, there was also an initial reluctance to change the way developing research software was made.
These experiences convinced me that researchers would benefit from understanding what software development entitles and adopting some of the best practices without needing to become software engineers themselves. If that could be achieved, research software would be of better quality, software as a research output would be easier to maintain, which would increase the likelihood of research results being reproducible for a longer time, the productivity among researchers that continuously engage in the development of research software could be improved; and, the time spent on directly working on research software, as a software engineer, could be increased to the benefit of the researchers themselves.
In summary, two situations motivated the development of this course. First, there is a need to increase confidence and independence in applying version control to research software among researchers attending similar courses. Second, we are enthusiastic about helping researchers adopt best practices in collaborative development to foster their productivity and improve the quality of research software.
Manuel. G. García
Research Software Engineer
Delft University of Technology
Content#
Course Description
Lecture Notes
Exercises
- Lesson 1 Episode 2 — Tracking changes with the index
- Lesson 1 Episode 2 — Stop tracking changes in a file
- Lesson 1 Episode 2 — Renaming tracked files
- Lesson 1 Episode 3 — Commit changes in a tracked file
- Lesson 1 Episode 3 — Follow the state of the repository in the commit routine
- Lesson 1 Episode 3 — Follow the state of the index in the commit routine
- Lesson 1 Episode 3 — Explore the changes recorded in the history
- Lesson 1 Episode 3 — Explore the changes recorded in the history
- Lesson 1 Episode 3 — Add lightweight tags to the history
- Lesson 1 Episode 3 — Load committed versions in the working tree
- Lesson 2 Episode 1 — get familiar with branches
- Lesson 2 Episode 1 — explore differences across branches
- Lesson 2 Episode 1 — commit in a secondary branch
- Lesson 2 Episode 1 — a first type of merge
- Lesson 2 Episode 1 — another type of merge
- Lesson 3 Episode 1 — Clone a reposiory and make a contribution
- Lesson 3 Episode 2 — Roles and Responsibilities
- Lesson 3 Episode 3 — Branching workflow
- Lesson 3 Episode 3 — Pull requests
- Lesson 3 Episode 3 — Forking workflow
- Lesson 4 Recapitulation — Implementing a Collaborative Workflow
- Lesson 4 Episode 1 — Code Reviews
- Lesson 4 Episode 2 — Guidelines for Contributions
- Lesson 4 Episode 2 — Choosing Licenses and Enabling Software Citation
Appendices