LESSON 3: Collaborative Software Development

LESSON 3: Collaborative Software Development#

Lecture notes for the lesson on an introduction to collaborative software development. This lesson is taught using presentations (to illustrate concepts), demostrations and exercises (to practice the concepts). The code examples in the lessons often indicate tasks that participant should do along with the instructor.

Learning Objectives:

  • To understand the key aspects of managing research software projects.

  • To make use of issues, code changes, and pull/merge requests to make contributions to a software project hosted in a collaborative platform.

  • To compose a software development team by assigning roles and responsibilities to a group of developers.

  • To contribute to the development of research software using a collaborative approach.

  • To choose between a centralised and shared collaborative workflow for a new software project.

  • To create contributions to software projects using one of the Git repository platforms such as GitHub.

Materials:

  • Collaborative software development: a presentation with general information about the lesson and illustrations for supporing the explanations of some of the concepts, and exercises.

  • Username form: a Google form to collect users-names of the collaborative platform that participants will use during the lesson. This serves as an example.

Preparation#

Instructor’s Note

  • The instructor must collect particiapant’s user names for GitHub/Gitlab the day before, so that they can be invited to collaborative repositories. The username form above could be use for that.

  • The instructor must create a repository for 3.1.3. Collaborating using this respository tempalte.

Recapitulation: Operations with Remotes#

[5 min]

Common operations with remotes

Instructor’s Note

  • Recapitulation on how local repostories and remotes are connected and how to work with remotes (Slides).

  • Recapitulation on what clone, fetch, merge, pull and push commands do.

Episode 1: Collaborative Platforms#

3.1.1. Connecting to Code Repositories#

[10 min]

  • Ask participants using Windows not to start Git Bash clicking on the desktop icon, as they did in Lesson 1. Instead,

    • use the app menu (the Windows logo)

    • pick up Git Bash from the list

    • launch Git Bash with the option Run as administrator available from the drop-down submenu. The participants may need to type in their credentials as local administrators. This gain authority to have SSH installing its own features in their laptop next.

Instructor’s Note

At their very first git push, Git might complain about a mismatch between the credentials of local and global administrator. The warning itself suggests another Git command as the remedy to this impasse.

Setting up SSH connection for GitHub#

Instructor’s Note

GitHub requires authentication via SSH to do pulls and pushes, but not for cloning public repositories. Explain what a SSH connection entitles (slides).

Some participants might have already set up SSH keys for GitHub. In this case, they can skip the next steps. They can check if they have SSH keys by running the following command in the terminal:

    ssh -T git@github.com # for GitHub

  • If a SSH connection must be set, do the following in a BASH terminal:

    1. Create a Key-pair inside the .ssh in the Home directory

          # move to Home directory
    cd ~
    # create key
    ssh-keygen -t ed25519 -C "your_email@example.com"
    # save to the default location and file name: ~/.ssh/id_ed25519

    2. Check the keys have been created

          ls ~/.ssh/

    3. Start the ssh-agent and add the private key to agent. This might be necessary for Windows users only.

          # start ssh-agent in the background
    eval "$(ssh-agent -s)":
```shell
    # start agent
    eval "$(ssh-agent -s)"

    # add private key
    ssh-add ~/.ssh/id_ed25519

    4. If a the private key was not save on the default directory, instruct SSH to use key files in different locations:

          ssh -i <path/private/keyfile>

      Instructor’s Note

      Window’s user would need to set up the ssh-agent* to start the automatically Mac and Linux user don’t have to worry about this.

    5. Copy public key to GitHub:

          clip < .ssh/id_ed25519.pub

      Instructor’s Note

      Go to GitHub, explain the basics of the interface and

    6. add the SSH key.

          Profile > Settings > SSH and GPG keys > New SSH key > Add SSH key

    7. Test SSH connection

          ssh -T git@github.com

      Instructor’s Note

      The message for a successful outcome is friendly and plain. Ask participants whether git@github.com has welcomed them.

Publishing Local Repository to GitHub#

[5 min]

  1. Create GitHub Repo: Go to GitHub and create an public empty repository called workshop. Repo description: workshop on collaborative development

  2. Add Remote to Local Repo: before this remove any existing remotes in the locare repository with: git remote remove <remote-alias>

Move back to the repo directory: ~/Desktop/ In your local repository (on the terminal), add the remote repository and push the content.

  • Connect to remote

        git remote add origin git@github.com:<user-name>/<repo-name>.git

  • Check that remote was added

        git remote -v
    git branch -M main # [Optional if config was changed. This will change the name of the main branch of the repo to make it more friendly]
    git push -u origin main

Check the Content is in GitHub#

Go back to your repo page and refresh the browser.

Instructor’s Note

Questions?

3.1.2. Exploring the GitHub GUI#

[5 min]

Collaborative platforms host and manage remote repositories to facilitate descentrilized collaborative development workflows.

Instructor’s Notes

Ask participants if they are familiar with GitHub. If not, give a short explanation of what it is for how to explore the GUI.

Mention GitLab at TU Delft as an alternative for a collaborative platform: https://gitlab.tudelft.nl/

3.1.3. Collaborating#

[5 min]

Participants are invited as collaborators to the check-in repository. A template to create a new repository is available in the check-in template. Participants must have permission to merge pull requets.

  1. Demo on how to invite collaborators using the check-in repository.

  2. Paticipant accept inviation via email or GitHub notifications.

Exercise 1 — Startig with Collaboration [10 mins]

Lesson 3 Episode 1 — Clone a reposiory and make a contribution

Time: 10 min

Please perform the following tasks individually.

  1. Clone the Check-in repository via SSH.

  2. Make a copy of the file check-in/template.md in the same directory; give it an anonymous name, ex. <name-initials><3-last-digits-phone>.md

  3. Open your copy of template.md and add something to the lists in the file.

  4. Commit your changes, and push them to the remote repository. You might experience difficulties doing that, follow the suggestions given by Git.

  5. Reflect on the difficulties you faced, and how we might avoid them.

Instructor’s Note

While completing this exercise, many participants will be warned by Git that they have to pull changes before pushing their contribution. This situation is expected and it should be used as a pre-amble to introduce 3.3.2. Centralised Workflow: Branching.

Answers
No answer are provided for this exercise.

Episode 2: Collaborative Development for Research Software#

3.2.1. Introduction to collaboration in software projects#

[5 min]

Instructor’s Note

  • A Quick introduction to collaborative development. Provide a short explanation on what it is and why it is important for research software development:

Developing high quality software requires more than programming and technical skill. Exceptionally good programmers can produce high quality software by themselves. But good programmers need to collaborate in order to develop complex, high quality software. —M. Garcia Alvarez

Topic to cover:

  • The software development life cycle.

  • Collaborative software development.

  • Differences between open and close collaboration.

  • Important considerations on open collaboration for research software.

  • When a collaborative approach in software development makes sense.

3.2.2 Managing Research Software Projects#

[2 min]

Instructor’s Note

Explain the following topics:

  • The importance of project management in developing software.

  • Key factors to consider.

    • Purpose

    • People

    • Time

    • Maintenance

  • Recommended management strategies for research software projects.

3.2.3 Organising Research Team for Collaborative Development#

[3 mins]

Instructor’s Note

Rores and Responsibilities

Describe the responsibilities for each role and why they are important for a research-software development project.

Roles:

  • Project owner

  • Administrator

  • Reviewer

  • Collaborator

Questions? [10 min]

Exercise 2 — Roles and Responsibilities

Lesson 3 Episode 2 — Roles and Responsibilities

Time: 6 min

Please perform the following tasks.

  1. Make teams of 3 or 4 people. You will work together during group exercises.

  2. Assign roles and responsibilities to each member; your team should have:

    • One project owner

    • One administrator

    • One or more collaborators. Project owners and administrators can also be collaborators.

    • Zero or more reviewers. Collaborators can also be reviewers.

  3. Choose a name for the team.

Answers
No answer are provided for this exercise.

Episode 3: Collaborative Workflows#

3.3.1. Documenting Issues#

[8 min]

Issues help to document ideas and tasks in a development project. They facilitate planning, discussing and tracking the progress of a software project.

Instructor’s Note

Do-along. Instruct participants on how to crate issues in the repository used in 3.1.3. Collaborating. Participants create at least one issue in such repository.

Collaborative workflows are estrategies to organise the work of a development team, so that developers can independently can undertake development task while keeping their work aligned with overal project goals. Two common estrategies that use version control and collaborative platforms as leverage are:

  • The branching workflow and

  • The forking workflow

3.3.2. Centralised Workflow: Branching#

Instructor’s Note

A short explanation on the branching workflow.

Exercise 3 — Branching workflow

Lesson 3 Episode 3 — Branching workflow

Time: 15 min

As a Team, work on the following coding taks using a branching workflow.

  1. [Administrator] Creates a repository using this template

  2. [Administrator] Invites all team members to the team’s repository as collaborators.

  3. [Team] Read the TODO.md file and each member choses one task for the next step.

  4. [Collaborator] each member opens an issue for the chosen task.

  5. [Collaborator] each member uses the branching model to complete the chosen task.

  6. [Collaborator] each member commits and pushs changes to the team’s repository.

Answers
No answer are provided for this exercise.

3.3.3. Pull Requests#

[5 min]

Explaination of what pull request are, and a live demonstation on a code repository ( e.g., GitHub or GitLab). Then teams follow the steps in the exercise below to create and merge pull requests.

Instructor’s Note

Ask participant if they already have experience with making pull request. Adapt your explanation accordingly.

Exercise 3 — Pull requests [6 min]

Lesson 3 Episode 3 — Pull requests

Time: 6 min

Working as a team, merge the changes made in the previous exercise into the main branch of the team’s repository.

  1. [Collaborators] create a pull request for their own branch. Give your pull request a meaning name, and a short and clear description.

  2. Are there any conflicts? Resolve them using the GitHuB GUI. Ask for help if you need to.

  3. [Collaborators] Merge the pull request to the main branch using the method of their choice.

  4. [Collaborators] Check the main branch to confirm that your changes have been merged.

Answers
No answer are provided for this exercise.

3.3.4. Shared Workflow: Forking#

[5 min]

A short explanation on the forking and branching workflow for managing contribution to code reposiotries.

Exercise 3 — Forking Workflow

Lesson 3 Episode 3 — Forking workflow

Time: 15 min

Working in teams, apply FAIR principles to a Git repository using a FAIR software checklist.

  1. [Administrator] creates a repository for the team using the collab-faircode template repository. Name the team’s repository as -faircode

  2. [Team] Go thru the Fair software checklist and assign one item from the list to each team member. The chosen item will become tasks for the team members to work on.

  3. [Collaborators] open an issue in the team’s repository about the chosen item. Describe the task for each item in the issue.

  4. [Collaborators] Fork the team’s repository to their accounts.

  5. [Collaborators] Clone their forks onto thier local machine, work on their issues, and push changes to their forks.

  6. [Collaborators] Make a pull request from their forks to the base repository (team’s repostory), main branch.

Answers
No answer are provided for this exercise.

Instructor’s Note

Ask participants if they have Questions.

Lesson Summary#

[5 min]

  • SHH is a secure way to connect to Code repositories.

  • Collaborative workflows provide a way to organize a team around a software project.

  • Workflows: branching (centralized) and forking (shared)

  • High quality software requires good planning and management.

  • Adopting roles and responsibilities can help teams to organize their work.

Contents