LESSON 4: Managing Collaboration and Best Practices

LESSON 4: Managing Collaboration and Best Practices#

Lecture notes for the lesson on managing collaboration and best practices. Most of the content in this lesson aims to present some best-practices for developing research software and lead an open discussion about when to apply them.

Work in progress

This part is work in progress. A revised version will be available soon.

These notes contains the following pointers for the instructor:

  • Numbers between [] are indicative of how much time should be spend in each topic or exercise to keep in track with the lesson schedule.

  • The text in Instructor note contain explanations or reminders for the instructor. For example:

    Instructor’s Note

    An SSH key must be set to push changes to a remote repository in GitHub.

Presentation

This contains general information about the lesson and illustrations for supporing the explanations of some of the concepts, and

Collaborative software development

i. Recapitulation: Collaborative Workflows#

Participants complete a group exercise to recap the content of Lesson 3.

Exercise 1 — Implement a Collaborative Workflow

Lesson 4 Recapitulation — Implementing a Collaborative Workflow

Time: 15 min

Working in teams, define and implement a workflow of your choice (branching/forking) to collaborate in a repository. Names between [] indicate who in the team should engage in each activity.

  1. [Administrator] create a repository for the team using the template: WorkshopGitcodev/collab-review

  2. [Team] discuss and agree on which workflow to implement for this exercise.

  3. [Team] each member choses one task from the faircode-checklist.md and make changes.

  4. [Team] each member opens a pull request to the main branch with the their changes Important: Do not merge.

  5. [Team] each member makes some other changes to the repository, commits and push.

  6. [Team] go back to your pull request and see how the latest changes affected your pull request. Do not merge.

Answers
No answer are provided for this exercise.

Episode 1: Managing Collaboration#

4.1.1. Code Reviews#

This lesson will be completed later.

Exercise 2 — Code Reviews [10 mins]

Lesson 4 Episode 1 — Code Reviews

Time: 15 min

Working in teams. Practice reviewing code in pull requests created in the last exercise on GitHub. Names between [] indicate who in the team should engage in each activity.

  1. [Author] Assign one or two team members as reviewers in your pull request (PR).

  2. [Reviewer] Reviews, discuss, and suggest changes the pull request(s) following recommendation mentioned so far.

  3. [Author] Make changes to PR based on the reviewer(s) suggestions, and updates the PR.

  4. [Reviewer] Approves the PR.

  5. [Author] Merges the PR into the repository.

4.1.2. Contributing Guidelines#

Exercise 3 — Guidelines for Contributions [10 mins]

Lesson 4 Episode 2 — Guidelines for Contributions

Time: 10 min

Working individually. Add contributing guidelines to the very repository used in Lessons 1 and 2. Use the template in: manuGil/fair-code to create your own guidelines.

Episode 2: Licensing and Citation#

4.2.1. Open Source Licenses#

4.2.2. Software Citation#

Exercise 3 — hoosing Licenses and Enabling Software Citation [10 mins]

Lesson 4 Episode 2 — Choosing Licenses and Enabling Software Citation

Time: 10 min

Working individually. Add a license and citation file to the repository used in Lesson 1 and 2 (workshop?).

  1. Add an opensource license to the remote repository. Use the Creative Common license tool to decide which license to use: https://chooser-beta.creativecommons.org

  2. Use this tool to generate a CITATION file and add it to your remote repository:

    • Search the Internet for: cffinit

Episode 3: Releasing Software#

4.3.1. Semantic Versioning#

4.3.1. Software Releases#

5. EXERCISE 6.#