CDU data science team blog: Creating a branch and using issues

Zoë Turner

In the GitHub SOP the blog refers to the GitHub flow which is self explanatory around how to create and manage branches but within the team we have a few steps related to Issues that are not included in the flow.

Why issues are useful

Issues are a searchable source of information in GitHub and are used in the team to highlight problems but also act as conversations. As a branch is a direct copy of another branch, usually main, the README should not have any reference to the issue that prompted the branch creation.

The issue needs to be detailed enough that another person, who has no prior knowledge of the repository, can understand it. This may require references to other systems, full details of data locations (server, schema, table in SQL for example) and avoid acronyms where possible.

Naming branches

In all repositories (except for blogs) every branch should correspond to an issue and have a title format of number from the issue with a short version of the title. For example, 40-blog-distill when the issue is Blog about the distill template. Issues can, and should, be linked to pull requests but until the pull request is made there is no other link to an issue from a branch other than a reference in the name.

Blogs sites are an exception

Where an issue exists, like in the example Blog about the distill template this should have a correspondingly named branch, however, more often than not blogs and posts are created separate to “issues”. In this circumstance it is ok to use branch names like the one used for this blog creating-branch-issues.

Closing an issue

All issues should be closed either by linking to pull request or closed with an explanation as to why it can be closed. Sometimes issues are raised that don’t have enough explanations or don’t become work, even then, a closing message is needed for future reference.

Create branches from GitHub

It is possible to create a branch from an Issue whilst in GitHub, this option appears in the right hand menu under Development which is also where other pull requests can be linked to issue (both closed and open).

If you use this code will appear to be used locally on the computer in the terminal, copy and right click in the RStudio terminal to paste.

Note that if you use a development branch that the new branch will be from main which you may not necessary want.

Summary

Always create an issue (unless it’s a blog site)
Always create a corresponding branch using the issue number and short name
Link issues to pull requests

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Citation

For attribution, please cite this work as

Turner (2022, May 3). CDU data science team blog: Creating a branch and using issues. Retrieved from https://cdu-data-science-team.github.io/team-blog/posts/2022-05-03-creating-a-branch-and-using-issues/

BibTeX citation

@misc{turner2022creating,
  author = {Turner, Zoë},
  title = {CDU data science team blog: Creating a branch and using issues},
  url = {https://cdu-data-science-team.github.io/team-blog/posts/2022-05-03-creating-a-branch-and-using-issues/},
  year = {2022}
}