In DataScienceILC/tlsc-dsfb26v-20_workflows: Bookdown site for workflows course
Git collaboration {#gitcollaboration}
knitr::opts_chunk$set(echo = TRUE)
les <- 5
In this lesson you will get to know many useful tools for collaboration in Github. You are required to apply them in your Data Science Projecticum
Learning aims
After this lesson you can do the following tasks with github and Rstudio:
Issues
- Creating issues
- Assigning issues
- Fixing an issue [
fixes #<issue_number>]
Kanban & automation
- Assigning tasks
- Kanban columns
- Labels
- Milestones
- Projects
- using am agile workflow in general
Branches
- Creating branches
- Assigning an issue to a branch
Pull requests
- Creating a pull request
- Merging a branch into
main
- Deleting a stale branch
Github flow
The workflow proposed below is documented here:
##### Exercise `r les` {-}
Study the Github Flow Documentation site mentioned above
In your own words: write a summary on how this flow works (remember to save all answers to questions in your .Rmd file). Discuss it with your Projecticum partner. See to it that you two really understand all the steps of the flow mentioned in the documentation.
Issues
Github issues are the core for collaboration with people within and outside your code project. Issues can be used for external people to report a bug, a feature request or a question regarding functionality or implementation. People using for example your package can ask questions or report problems in the form of an issue. Below, an example is shown for the {dplyr} R-package, which has a huge user community.
knitr::include_graphics(
here::here(
"images",
"dplyr_issues.png"
)
)
Posting an issue when you encounter an error or bug helps developers create robuster code and is the core driving force for developing new features or resolving problems in open source software. Opening issues is an easy way to start contributing to the open source community.
##### Exercise `r les` {-}
**Looking at issues to learn from others**
a) Review the first bug you can find on this page:
https://github.com/tidyverse/dplyr/issues
Read the description and the proposed solutions if any. Describe in your own words what the bug relates to. Discuss the bug with a fellow student.
b) Review issue `#5640` in the `{dplyr}` issues. Why was this issue closed? Was the issue resolved for the user who reported it?
Creating issues in your project repo
When collaborating together on project repository, you can create issues to stay on track for the different actions that need to be undertaken. Issues can be related to adding functionality (code) to the project, but also to report a bug or to request the addition or improvement of documentation. You can create an issue by opening the Issues tab and creating a new issue by clicking the green New issue button. A form will open where you can add a title and further remarks to document your issue. The formatting of the Leave a comment field can be entered using Markdown formatting. When creating an issue, it is important to assign (preferable one) person to the issue. You can also choose a label, and if needed you can customize the label categories. When a Kanban/Project is also linked to the organization or repo, you can also add the issue to a Kanban board. More about Kanban here \@ref(kanban-and-automation). When creating a new issue, you can also add a Milestone. We will discuss this later \@ref(milestones)
##### Exercise `r les` {-}
**The teachers have created a projecticum organisation on github, use the repository you have made here for this exercise.**
Follow these steps to complete this exercise:
1. Add your first issue to the issue list in your projecticum: This issue has to be related to adding valuable project documentation to your repository. For example: start with editing the README.md file to contain information on the project and the repo.
1. Ensure that the issue is also visible on the Kanban board of the project
1. Assign the issue to your co worker (agree on an issue first, so make this exercise together with your project companion)
1. Assign the issue to the Github project linked to the repo (if you have no project, create it and ad the repo as a linked repo to the github project)
1. Create a new branch in the repo that you call issue_
1. Clone (or pull if you already cloned the repo) the new branch to your RStudio projecticum project environment
1. Solve the issue in your 'local' version of the repo
1. Write a commit that adresses the issue solved and that also includes this phrase: "fixes #". Replace the `` part with the issue number that you are trying to push.
1. Generate a pull request and merge the pull request to the main branch
1. Check the issue list to see if the issue was automatically closed
1. Check the issue on the project Kanban board to see if it was automatically put in the `closed` column.
1. Delete the branch related to the issue you just resolved
## One issue per change, one issue per branch [`fixes #` and `new branch`]
In the exercise above we saw how to open, fix and automatically close an issue. But what defines an issue and how would you prevent working on the same piece of code when working together.
In the main [resource](https://guides.github.com/introduction/flow/) used for this piece in the course, we can read this about branches (as was already explained previously):
wzxhzdk:2
When working together in git/github, this flow is extremely important to agree upon and than stick to it.
## Kanban and automation
When using a github project, you can setup a Kanban board to track issues. Issues on the Kanban are also resolved when you close an issue, either manually or through a pull request.
## Milestones
Milestones in Gihub can be sonsidered as Agile/SCRUM sprints. So each sprint is associated with one or multiple milestones that need to be resolved at the end of each sprint.
##### Exercise `r les` {-}
To complete this exercise, you need to complete the following steps:
1. Create at least 2 milestones for the first sprint of your projecticum project
1. Create a number of *issues that need to be resolved for these 2 milestones to be completed (link these issue to the appropriate milestone you created in the previous step)
1. Put these issues on the Kanban board in the 'In progress' column
1. Create branch for each issue, you just created in Github
1. Synchronize you local branches in RStudio, with the remote branches
1. Switch to a branch of an issue you want to work on
1. Start working and solving an issue
1. When you are done with the issue: comit your changes, firt to you local issue-branch, than puch the commit to the remote (remember to use the 'fixes #' phrase in your commit
1. Create a pull request to the 'main'branch
1. Merge the pull request into main
1. Observe what happened on the Kanban board. Where did the issue you just resolved land? What happened to the milestone?
1. Delete the branch related to the issue you just resolved
*Remember: a good issue is so small that it can be tackled in approximately a day's work or less!
^An issue can basically be anything, but here we mean something than can be comited to a repo, such as a piece of code, a dataset or documentation.
## Agile/Scrum {#agilescrum}
## Resources
https://github.com/jvandemo/github-scrum-workflow
https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests
## GitHub scrum workflow
Turn any GitHub repository into a simple but powerful agile work environment.
**Free**, **simple** and **fast** so you can focus on the actual coding!
**Summary:**
+ [How it works](#how-it-works)
+ [1. Create issues as backlog items](#1-create-issues-as-backlog-items)
+ [2. Add labels to issues](#2-add-labels-to-issues)
+ [3. Define sprints as milestones](#3-define-sprints-as-milestones)
+ [Overview](#overview)
+ [Helpful links](#helpful-links)
+ [Change log](#change-log)
---
## Agile/SCRUM
[Adapted from Wikipedia - The free Ecyclopedia](https://en.wikipedia.org/wiki/Agile_software_development)
In software development, agile (here written as Agile) practices approach discovering requirements and developing solutions through the collaborative effort of self-organizing and cross-functional teams. Their customer(s)/end user(s) play a pivotal role in the work process and are involved in reviews at regular intervals. It advocates adaptive planning, evolutionary development, early delivery, and continual improvement, and it encourages flexible responses to change.
### Agile explained
The Agile way of working is also very suitable for Scientific projects that have elements of Data Science and Software development. Because it is short-cycle development and prototyping, it is very useful in projects where different tasks need to be integrated in a tool or workflow or analysis.
During the Data Science Projecticum, we will require you (within you project team, to apply the Agile way of working).
### SCRUM
In practical sense, scrum is the collection of meetings and the tools used to administer the workload. The central tool that is being used to monitor all activities is called the 'Project Backlog'. You can look at this 'Project Backlog as the collection of all the work that needs to be done to complete the full project. Because the Agile way of work does not work with long term planning, but works according short cycles of developing a product, a service or perform a study, or involve stakeholders, the 'Project Backlog' is where all the team members go regularly together to agree on what needs to be done next.
The short cycles of working on developing new features, running computations, performing experiments, interviewing customers and stake-holders and acquiring new tools are called 'Sprints'. In each sprint, which typically lasts 3 working weeks, a number of items from the Backlog are 'moved' to the so-called 'Sprint Backlog'. During regular weekly sessions discussion take place which items need to go from the 'Project Backlog' to the 'Sprint Backlog' in order to add value to the project. These sessions are called 'Sprint planning'. At the start of each sprint a single
### Workflow
Image: [Scrum primer](http://www.scrumprimer.org/overview).
### Github organization and Data Science Projecticum
To effectively collaborate with your partner on the Data Science Projecticum Assignment, you will need to setup a new organization in Github. Each project assignment comes with its own 'Acronym'. Use this acronym to setup the organization. Once the organization is created you can start working on your project. Be sure to add all supervisors to your organization and the repositories for your project.
## How it works in Detail
- items are reported as **issues**
- points and meta data are assigned to items as **labels**
- **milestones** are used to group issues in sprints
## 1. Create issues as backlog items
To create a new backlog item, just create a new issue.
Once a new issue has been created, assign it the right labels and/or assign it to a sprint (milestone).
Issues allow you to have a conversation about the item and even allow you to create task lists inside the issue using [GitHub's markdown](https://guides.github.com/features/mastering-markdown/).
## 2. Add labels to issues
Add the following labels to your repository:
### Priorities
`priority` labels allow you to prioritize items in your backlog e.g.:
- `priority: lowest`
- `priority: low`
- `priority: medium`
- `priority: high`
- `priority: highest`
### Types
`type` labels allow you to easily filter items (issues) in the dashboard e.g.:
- `type:bug`: bug
- `type:chore`: chore, maintenance work
- `type:feature`: new feature
- `type:infrastructure`: infrastructure related
- `type:performance`: performance related
- `type:refactor`: refactor
- `type:test`: test related
### Other
You can define and assign custom labels that you need within your workflow or organization.
## 3. Define sprints as milestones
You can create a milestone for every sprint and add items (issues) from the backlog to a milestone.
This allows you to group items in sprints and track them by milestone in your [issue dashboard](https://github.com/issues).
The backlog then consists of all items (issues) that have no `milestone` attached to it.
**TIP**: Use `no:milestone` in the search field on your [issue dashboard](https://github.com/issues) to find backlog items.
## Helpful links
- [Mastering GitHub issues](https://guides.github.com/features/issues/)
- [Mastering GitHub markdown](https://guides.github.com/features/mastering-markdown/)
- [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/)
## Working as an Agile team
The follow up for this lesson will be an online demo provided by one the SCRUM masters at the HU. In this demo we will focus on the good practices when working in an Agile/SCRUM team and learn how to apply the baics in your own project work.
## Portfolio assignment `r paste0(les, " ")` {-}
**Github documentation**
A) Study the github documentation on "Project Boards" [here](https://docs.github.com/en/github/managing-your-work-on-github/managing-project-boards)
B) Setup a project for your projecticum in your github account.
C) The teachers have created a specific repo for your projecticum project and have added you to them, Link this repo to the project you just created.
DataScienceILC/tlsc-dsfb26v-20_workflows documentation built on July 4, 2025, 5:49 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.
Git collaboration {#gitcollaboration}
knitr::opts_chunk$set(echo = TRUE) les <- 5
In this lesson you will get to know many useful tools for collaboration in Github. You are required to apply them in your Data Science Projecticum
Learning aims
After this lesson you can do the following tasks with github and Rstudio:
Issues
- Creating issues
- Assigning issues
- Fixing an issue [
fixes #<issue_number>]
Kanban & automation
- Assigning tasks
- Kanban columns
- Labels
- Milestones
- Projects
- using am agile workflow in general
Branches
- Creating branches
- Assigning an issue to a branch
Pull requests
- Creating a pull request
- Merging a branch into
main - Deleting a stale branch
Github flow
The workflow proposed below is documented here:
##### Exercise `r les` {-}
Study the Github Flow Documentation site mentioned above
In your own words: write a summary on how this flow works (remember to save all answers to questions in your .Rmd file). Discuss it with your Projecticum partner. See to it that you two really understand all the steps of the flow mentioned in the documentation.
Issues
Github issues are the core for collaboration with people within and outside your code project. Issues can be used for external people to report a bug, a feature request or a question regarding functionality or implementation. People using for example your package can ask questions or report problems in the form of an issue. Below, an example is shown for the {dplyr} R-package, which has a huge user community.
knitr::include_graphics( here::here( "images", "dplyr_issues.png" ) )
Posting an issue when you encounter an error or bug helps developers create robuster code and is the core driving force for developing new features or resolving problems in open source software. Opening issues is an easy way to start contributing to the open source community.
##### Exercise `r les` {-}
**Looking at issues to learn from others**
a) Review the first bug you can find on this page:
https://github.com/tidyverse/dplyr/issues
Read the description and the proposed solutions if any. Describe in your own words what the bug relates to. Discuss the bug with a fellow student.
b) Review issue `#5640` in the `{dplyr}` issues. Why was this issue closed? Was the issue resolved for the user who reported it?
Creating issues in your project repo
When collaborating together on project repository, you can create issues to stay on track for the different actions that need to be undertaken. Issues can be related to adding functionality (code) to the project, but also to report a bug or to request the addition or improvement of documentation. You can create an issue by opening the Issues tab and creating a new issue by clicking the green New issue button. A form will open where you can add a title and further remarks to document your issue. The formatting of the Leave a comment field can be entered using Markdown formatting. When creating an issue, it is important to assign (preferable one) person to the issue. You can also choose a label, and if needed you can customize the label categories. When a Kanban/Project is also linked to the organization or repo, you can also add the issue to a Kanban board. More about Kanban here \@ref(kanban-and-automation). When creating a new issue, you can also add a Milestone. We will discuss this later \@ref(milestones)
##### Exercise `r les` {-}
**The teachers have created a projecticum organisation on github, use the repository you have made here for this exercise.**
Follow these steps to complete this exercise:
1. Add your first issue to the issue list in your projecticum: This issue has to be related to adding valuable project documentation to your repository. For example: start with editing the README.md file to contain information on the project and the repo.
1. Ensure that the issue is also visible on the Kanban board of the project
1. Assign the issue to your co worker (agree on an issue first, so make this exercise together with your project companion)
1. Assign the issue to the Github project linked to the repo (if you have no project, create it and ad the repo as a linked repo to the github project)
1. Create a new branch in the repo that you call issue_
1. Clone (or pull if you already cloned the repo) the new branch to your RStudio projecticum project environment
1. Solve the issue in your 'local' version of the repo
1. Write a commit that adresses the issue solved and that also includes this phrase: "fixes #". Replace the `` part with the issue number that you are trying to push.
1. Generate a pull request and merge the pull request to the main branch
1. Check the issue list to see if the issue was automatically closed
1. Check the issue on the project Kanban board to see if it was automatically put in the `closed` column.
1. Delete the branch related to the issue you just resolved
## One issue per change, one issue per branch [`fixes #` and `new branch`]
In the exercise above we saw how to open, fix and automatically close an issue. But what defines an issue and how would you prevent working on the same piece of code when working together.
In the main [resource](https://guides.github.com/introduction/flow/) used for this piece in the course, we can read this about branches (as was already explained previously):
wzxhzdk:2
When working together in git/github, this flow is extremely important to agree upon and than stick to it.
## Kanban and automation
When using a github project, you can setup a Kanban board to track issues. Issues on the Kanban are also resolved when you close an issue, either manually or through a pull request.
## Milestones
Milestones in Gihub can be sonsidered as Agile/SCRUM sprints. So each sprint is associated with one or multiple milestones that need to be resolved at the end of each sprint.
##### Exercise `r les` {-}
To complete this exercise, you need to complete the following steps:
1. Create at least 2 milestones for the first sprint of your projecticum project
1. Create a number of *issues that need to be resolved for these 2 milestones to be completed (link these issue to the appropriate milestone you created in the previous step)
1. Put these issues on the Kanban board in the 'In progress' column
1. Create branch for each issue, you just created in Github
1. Synchronize you local branches in RStudio, with the remote branches
1. Switch to a branch of an issue you want to work on
1. Start working and solving an issue
1. When you are done with the issue: comit your changes, firt to you local issue-branch, than puch the commit to the remote (remember to use the 'fixes #' phrase in your commit
1. Create a pull request to the 'main'branch
1. Merge the pull request into main
1. Observe what happened on the Kanban board. Where did the issue you just resolved land? What happened to the milestone?
1. Delete the branch related to the issue you just resolved
*Remember: a good issue is so small that it can be tackled in approximately a day's work or less!
^An issue can basically be anything, but here we mean something than can be comited to a repo, such as a piece of code, a dataset or documentation.
## Agile/Scrum {#agilescrum}
## Resources
https://github.com/jvandemo/github-scrum-workflow
https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests
## GitHub scrum workflow
Turn any GitHub repository into a simple but powerful agile work environment.
**Free**, **simple** and **fast** so you can focus on the actual coding!
**Summary:**
+ [How it works](#how-it-works)
+ [1. Create issues as backlog items](#1-create-issues-as-backlog-items)
+ [2. Add labels to issues](#2-add-labels-to-issues)
+ [3. Define sprints as milestones](#3-define-sprints-as-milestones)
+ [Overview](#overview)
+ [Helpful links](#helpful-links)
+ [Change log](#change-log)
---
## Agile/SCRUM
[Adapted from Wikipedia - The free Ecyclopedia](https://en.wikipedia.org/wiki/Agile_software_development)
In software development, agile (here written as Agile) practices approach discovering requirements and developing solutions through the collaborative effort of self-organizing and cross-functional teams. Their customer(s)/end user(s) play a pivotal role in the work process and are involved in reviews at regular intervals. It advocates adaptive planning, evolutionary development, early delivery, and continual improvement, and it encourages flexible responses to change.
### Agile explained
The Agile way of working is also very suitable for Scientific projects that have elements of Data Science and Software development. Because it is short-cycle development and prototyping, it is very useful in projects where different tasks need to be integrated in a tool or workflow or analysis.
During the Data Science Projecticum, we will require you (within you project team, to apply the Agile way of working).
### SCRUM
In practical sense, scrum is the collection of meetings and the tools used to administer the workload. The central tool that is being used to monitor all activities is called the 'Project Backlog'. You can look at this 'Project Backlog as the collection of all the work that needs to be done to complete the full project. Because the Agile way of work does not work with long term planning, but works according short cycles of developing a product, a service or perform a study, or involve stakeholders, the 'Project Backlog' is where all the team members go regularly together to agree on what needs to be done next.
The short cycles of working on developing new features, running computations, performing experiments, interviewing customers and stake-holders and acquiring new tools are called 'Sprints'. In each sprint, which typically lasts 3 working weeks, a number of items from the Backlog are 'moved' to the so-called 'Sprint Backlog'. During regular weekly sessions discussion take place which items need to go from the 'Project Backlog' to the 'Sprint Backlog' in order to add value to the project. These sessions are called 'Sprint planning'. At the start of each sprint a single
### Workflow
Image: [Scrum primer](http://www.scrumprimer.org/overview).
### Github organization and Data Science Projecticum
To effectively collaborate with your partner on the Data Science Projecticum Assignment, you will need to setup a new organization in Github. Each project assignment comes with its own 'Acronym'. Use this acronym to setup the organization. Once the organization is created you can start working on your project. Be sure to add all supervisors to your organization and the repositories for your project.
## How it works in Detail
- items are reported as **issues**
- points and meta data are assigned to items as **labels**
- **milestones** are used to group issues in sprints
## 1. Create issues as backlog items
To create a new backlog item, just create a new issue.
Once a new issue has been created, assign it the right labels and/or assign it to a sprint (milestone).
Issues allow you to have a conversation about the item and even allow you to create task lists inside the issue using [GitHub's markdown](https://guides.github.com/features/mastering-markdown/).
## 2. Add labels to issues
Add the following labels to your repository:
### Priorities
`priority` labels allow you to prioritize items in your backlog e.g.:
- `priority: lowest`
- `priority: low`
- `priority: medium`
- `priority: high`
- `priority: highest`
### Types
`type` labels allow you to easily filter items (issues) in the dashboard e.g.:
- `type:bug`: bug
- `type:chore`: chore, maintenance work
- `type:feature`: new feature
- `type:infrastructure`: infrastructure related
- `type:performance`: performance related
- `type:refactor`: refactor
- `type:test`: test related
### Other
You can define and assign custom labels that you need within your workflow or organization.
## 3. Define sprints as milestones
You can create a milestone for every sprint and add items (issues) from the backlog to a milestone.
This allows you to group items in sprints and track them by milestone in your [issue dashboard](https://github.com/issues).
The backlog then consists of all items (issues) that have no `milestone` attached to it.
**TIP**: Use `no:milestone` in the search field on your [issue dashboard](https://github.com/issues) to find backlog items.
## Helpful links
- [Mastering GitHub issues](https://guides.github.com/features/issues/)
- [Mastering GitHub markdown](https://guides.github.com/features/mastering-markdown/)
- [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/)
## Working as an Agile team
The follow up for this lesson will be an online demo provided by one the SCRUM masters at the HU. In this demo we will focus on the good practices when working in an Agile/SCRUM team and learn how to apply the baics in your own project work.
## Portfolio assignment `r paste0(les, " ")` {-}
DataScienceILC/tlsc-dsfb26v-20_workflows documentation built on July 4, 2025, 5:49 a.m.
**Github documentation**
A) Study the github documentation on "Project Boards" [here](https://docs.github.com/en/github/managing-your-work-on-github/managing-project-boards)
B) Setup a project for your projecticum in your github account.
C) The teachers have created a specific repo for your projecticum project and have added you to them, Link this repo to the project you just created.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.