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.

Learning Objectives:

  • To understand the importance of contribution guidelines and best practices to manage collaboration in research software projects.

  • To organise the activities of a software team that participates in a collaborative development workflow.

  • To understand the impact of code reviews and best practices on software quality.

  • To perform code reviews as part of a research software team.

  • To discuss best practices related to code reviews, licensing, citation, semantic versioning, and software releases.

Materials:

Managing collaboration and best practices: a presentation with general information about the lesson and illustrations for supporing the explanations of some of the concepts, and exercises.

i. Recapitulation: Collaborative Workflows#

Participants complete a group exercise to recapitulate 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 will be implemented in this exercise.

  3. [Team] each member chooses 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 pushes.

  6. [Team] each member goes back to their pull requests and see how the latest changes affected the pull requests. Do not merge.

Answers
No answer are provided for this exercise.

Episode 1: Managing Collaboration#

4.1.1. Code Reviews#

Provide an introduction in the form of a short lecture on code reviews and their importance in collaborative software development. The following are some points to present and discuss with the participants:

  • Reasons for code reviews:

    • Sharing knowledge

    • Spreding ownership

    • Unifiying development practices

    • Quality control

  • Aspect to focus on during code reviews.

  • Giving feedback as part of the code review process.

  • Explicit communication.

  • Documenting code revies as an author .

  • Best practices in code reviews: do’s and don’ts.

Instructor’s Note

Slides 6 to 16 of the presentation above contain information on this topic.

The instructor demonstrates how to conduct a code review on the collaborative platform used in the course (GitHub, GitLab, etc.). The instructor can use the pull request created in the previous exercise as an example. Depending on the platform, the instructor can show how to:

  • Assign reviewers to a pull request/merge request.

  • Add comments to the code.

  • Suggest changes to the code.

  • Approve the pull request/merge request.

  • Merge the pull request/merge request into the main branch.

  • Close the pull request/merge request.

Exercise 2 — Code Reviews [10 mins]

Lesson 4 Episode 1 — Code Reviews

Time: 10 min

Working in teams. Practice reviewing code in pull requests created in the previous exercise. 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 after being approved for at least one reviewer.

Answers
No answer are provided for this exercise.

4.1.2. Contributing Guidelines#

Contributing guidelines are a set of rules and best practices that help to ensure that contributions to a project are consistent, high-quality, and easy to review. They can include information on how to write code, how to format code, how to write commit messages, how to write documentation, and how to submit pull requests. Provide an explanation on the purpose and importance of contributing guidelines in collaborative software development, and show some examples of the conent in a CONTRIBUTING.md file.

Examples:

Instructor’s Note

The instructor facilitess a discussion on the importance of contributing guidelines in collaborative software development before the exercise. Somoe of the topics that can be discussed are:

  • Why are contributing guidelines important?

  • How contributing guidelines can help to ensure that contributions to a project are consistent, high-quality, and easy to review?

  • What are the main components of a contributing guideline and how to adapt them depending of the nature of the project?

  • Why contributors should follow the contributing guidelines?

Exercise 3 — Guidelines for Contributions [10 mins]

Lesson 4 Episode 2 — Guidelines for Contributions

Time: 10 min

  1. Working individually, use the CONTRIBUTING.md template provided in manuGil/fair-code to add contributing guidelines to the very repository used in Lessons 1 and 2.

  2. Adapt the template to your repository as long as time allow it.

Answers
No answer are provided for this exercise.

Episode 2: Licensing and Citation#

Explain and discuss the importance of software licenses and software citation for software.

4.2.1. Open Source Licenses#

Explain the importance of open source licenses and how they can help to protect the rights of the authors and users of the software. Discuss the different types of open source licenses, such as permissive licenses (e.g., MIT, Apache) and copyleft licenses (e.g., GPL), and their implications for software development (reuse of soruce code) and distribution. Limit the explantions to the most common licenses, such as MIT, Apache, and GPL without focusing too much on the legal details.

It is important to mention what it is assumed (by law) when software provides no licensing information. In such cases, it is assumed that software cannot be use by anyone else than the author.

Also explain why software licensing is diffrent than data and digital content licensing. For exaple, why Creative Common licenses should not be used for software.

Instructor’s Note

If your institutions has a software policy for research software, it is important to mention it to the particpants, and provide relevant details about guidelines provided by the university to publish open source software.

4.2.2. Software Citation#

Explain how citations files are used to provide information about the software and its authors, and how they can be used to generate citations in different formats. In GitHub, for example, the citation file is called CITATION.cff citation file can be used to generate citations in different formats, such as BibTeX, APA, and MLA.

Provide a demo on how to create .cff files using this CFFInit Tool

Exercise 3 — Choosing 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 files to the repository used in Lesson 1 and 2.

  1. Use the Open Source Initiative license tool to pick an open source license of your choice: https://opensource.org/licenses

  2. Add a LICENSE file to your remote repository. Check the GitHub documentation to know how to add a license file. If you have to, edit the license file to include auhtors name, year, etc.

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

    • Search the Internet for: cffinit

Answers
No answer are provided for this exercise.

Episode 3: Releasing Software#

Releasing software is an important step in the software development process. It allows developers to share their work with others and to get feedback on their code. It also allows users to use the software and to report bugs or issues.

4.3.1. Semantic Versioning#

Explain the concept of semantic versioning and how it helps to have a common language for communicating about software releases. Discuss the different components of a semantic version number, such as major, minor, patch versions, and their implications for software development and distribution.

4.3.1. Software Releases#

Explain the importance of releasing software and how it can help to ensure that the software is stable, reliable, and easy to use. Discuss the different types of software releases, such as alpha, beta, release candidates and stable releases, and their implications for software development and distribution.

Demonstrate how to create a software release in the collaborative platform used in the course (GitHub, GitLab, etc.).

Explain and discuss the role and importance of keeping a changelog file in the software repository. A changelog file is a file that contains a list of changes made to the software, such as bug fixes, new features, and improvements. It is important to keep a changelog file up to date so that users can see what has changes between releases, and how those changes may affect them.

Lesson Summary#

[5 mins]

  • Code reviews a essential to produce high quality software.

  • Be mindful when giving feedback to someone else code.

  • Collaborative guidelines let potential collaborators to know how they can contribute to a software.

  • It is important to think about citing an licensing your software.

  • Use semantic versioning when releasing software.

Follow-up Material

Contents