Mini tutorial on Git and GitHub #81
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dalonsoa
requested review from
jamesturner246,
TinyMarsh,
HarmonicReflux,
alexdewar and
SaranjeetKaur
SaranjeetKaur
approved these changes
Nov 27, 2024
There was a problem hiding this comment.
Thanks @dalonsoa! This is really nice and comprehensive. Just added some very minor suggestions.
|
|
||
| Version control is an essential part of software development good practices, specially when combined with an online repository that enables easy collaboration with other people. One of the most common tool combination is using `git` for version control and `GitHub` as the online repository. | ||
|
|
||
| Despite being more common nowadays, and despite the long term benefits it brings to the table, many software development done in a reseach environments like universities does not use version control, maybe because researchers do not know about it or because they do not know how to do it right, seing it more as a burden. This mini-tutorial on Git and, specially, GitHub aims to help users with those first steps and point them in the right direction to learn more about the topic. |
There was a problem hiding this comment.
Suggested change
| Despite being more common nowadays, and despite the long term benefits it brings to the table, many software development done in a reseach environments like universities does not use version control, maybe because researchers do not know about it or because they do not know how to do it right, seing it more as a burden. This mini-tutorial on Git and, specially, GitHub aims to help users with those first steps and point them in the right direction to learn more about the topic. | |
| Despite being more common nowadays, and despite the long term benefits it brings to the table, many software development done in research environments like universities does not use version control, maybe because researchers do not know about it or because they do not know how to do it right, seeing it more as a burden. This mini-tutorial on Git and, specially, GitHub aims to help users with those first steps and point them in the right direction to learn more about the topic. |
|
|
||
| ## Resources and courses | ||
|
|
||
| This blog post is not a course but just a minimalistic how-to to use `git` and `GitHub` effectivly, specially when collaborating with others. We strongly recommend checking more full-feature training materials on the topic like the [Software Carpentry](https://software-carpentry.org/) or [Code Refinery](https://coderefinery.org/lessons/) courses or the courses created for the [Early Career Researcher Institute (ECRI)](https://www.imperial.ac.uk/students/academic-support/graduate-school/professional-development/doctoral-students/research-computing-data-science/courses/) by the [Research Software Engineering team at Imperial](https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/): |
There was a problem hiding this comment.
Suggested change
| This blog post is not a course but just a minimalistic how-to to use `git` and `GitHub` effectivly, specially when collaborating with others. We strongly recommend checking more full-feature training materials on the topic like the [Software Carpentry](https://software-carpentry.org/) or [Code Refinery](https://coderefinery.org/lessons/) courses or the courses created for the [Early Career Researcher Institute (ECRI)](https://www.imperial.ac.uk/students/academic-support/graduate-school/professional-development/doctoral-students/research-computing-data-science/courses/) by the [Research Software Engineering team at Imperial](https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/): | |
| This blog post is not a course but just a minimalistic how-to to use `git` and `GitHub` effectively, specially when collaborating with others. We strongly recommend checking more full-feature training materials on the topic like the [Software Carpentry](https://software-carpentry.org/) or [Code Refinery](https://coderefinery.org/lessons/) courses or the courses created for the [Early Career Researcher Institute (ECRI)](https://www.imperial.ac.uk/students/academic-support/graduate-school/professional-development/doctoral-students/research-computing-data-science/courses/) by the [Research Software Engineering team at Imperial](https://www.imperial.ac.uk/admin-services/ict/self-service/research-support/rcs/service-offering/research-software-engineering/): |
|
|
||
| You can read more about [Using GitHub issues](https://imperialcollegelondon.github.io/introductory_grad_school_git_course/l3-01-issues/index.html) in our introductory Git and GitHub course. | ||
|
|
||
| {: .no-caption style="display:block;margin:auto;width:86%" } |
There was a problem hiding this comment.
Suggested change
| {: .no-caption style="display:block;margin:auto;width:86%" } | |
| {: .no-caption style="display:block;margin:auto;width:86%" } |
| - **Issues are a sort of ToDo list - they help to organise what needs to be done**. Use labels to sort the issues in categories and write meaningful issue titles to help the reader quickly figuring out what they are about. | ||
| - **Writing good issues takes time, but it is time well invested if done right**. Writing an issue is not just _writing_ but also reflecting on what needs to be written, which means reflecting on the problem to solve, being this fixing a bug or adding new functionality. As you might not be the one finally addressing the issue, include clear explanations and context that are understandable to others. They might not know what you know. Also, if there's a tool or solution that you think will work well to tackle that issue, do mention it. | ||
| - **Complex issues should be broken down into sub-issues that are more manageable**. This enables team members (or yourself if you work alone on the project) to work in parallel in different aspects of the code. It also leads to smaller pull requests, which are easier to review. Use [task lists](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) to organise the sub-issues within large, umbrella issues. | ||
| - **Before working on an issue, claim it (or assign it to it yourself)**. This is essential in a collaborative propject to make sure that no two peole are working on the same issue without knowing it, which would be a wasteful duplication of efforts. |
There was a problem hiding this comment.
Suggested change
| - **Before working on an issue, claim it (or assign it to it yourself)**. This is essential in a collaborative propject to make sure that no two peole are working on the same issue without knowing it, which would be a wasteful duplication of efforts. | |
| - **Before working on an issue, claim it (or assign it to it yourself)**. This is essential in a collaborative project to make sure that no two people are working on the same issue without knowing it, which would be a wasteful duplication of efforts. |
| {: .no-caption style="display:block;margin:auto;width:86%" } | ||
|
|
||
| - **Pull requests are the means to incorporate new features (or fix bugs) to the base code when collaborating**. It is therefore the gateway for code growth, so an incredibly important step. | ||
| - **They enable others to provide feedback, suggest changes and try your code**. This las bit is important since, regardless of how many continuous integration tools we put in place, in the end something that works fine in someone's computer might not work so well in other's. |
There was a problem hiding this comment.
Suggested change
| - **They enable others to provide feedback, suggest changes and try your code**. This las bit is important since, regardless of how many continuous integration tools we put in place, in the end something that works fine in someone's computer might not work so well in other's. | |
| - **They enable others to provide feedback, suggest changes and try your code**. This last bit is important since, regardless of how many continuous integration tools we put in place, in the end something that works fine in someone's computer might not work so well in other's. |
|
|
||
| {: .no-caption style="display:block;margin:auto;width:69%" } | ||
|
|
||
| - **PRs reviews are meant to make the PR better**. They are a means of quality control, so reviweing them is a serious task that need proper attention from the reviewer. |
There was a problem hiding this comment.
Suggested change
| - **PRs reviews are meant to make the PR better**. They are a means of quality control, so reviweing them is a serious task that need proper attention from the reviewer. | |
| - **PRs reviews are meant to make the PR better**. They are a means of quality control, so reviweing them is a serious task that needs proper attention from the reviewer. |
| - **PRs reviews are meant to make the PR better**. They are a means of quality control, so reviweing them is a serious task that need proper attention from the reviewer. | ||
| - **Comments and suggestions need to be respectful, positive and pro-active, with justified suggestions and requested changes**. It should be clear what is a suggestion - and therefore optional - and what a request for a change, so the PR author can action them appropriately. | ||
| - **They are a learning tool for reviewers**, as much as for the PR authors. They can learn about new tools, commands or way of doing things. | ||
| - **For some PRs it might be necessary to have several rounds of reviews to nail the content**. This is normal, specially for big PR, but it should not take ages to have a PR merged. That is annoying for both author and reviewers. To avoid this, both authors and reviwers should pay attention to what is being requested and actioned, so nothing is forgotten, and doing so as swiftly as possible, considering their other commitments. |
There was a problem hiding this comment.
Suggested change
| - **For some PRs it might be necessary to have several rounds of reviews to nail the content**. This is normal, specially for big PR, but it should not take ages to have a PR merged. That is annoying for both author and reviewers. To avoid this, both authors and reviwers should pay attention to what is being requested and actioned, so nothing is forgotten, and doing so as swiftly as possible, considering their other commitments. | |
| - **For some PRs it might be necessary to have several rounds of reviews to nail the content**. This is normal, specially for big PR, but it should not take ages to have a PR merged. That is annoying for both author(s) and reviewer(s). To avoid this, both author(s) and reviewer(s) should pay attention to what is being requested and actioned, so nothing is forgotten, and doing so as swiftly as possible, considering their other commitments. |
|
It seems there have been some changes in the ReCode repo and the links that point to it are no longer working. I'll see what needs fixing and possibly add a separate PR to address those. |
Co-authored-by: Saranjeet Kaur <s.bhogal@imperial.ac.uk>
|
@SaranjeetKaur , some your comments where about spell issues and typos I fixed in 6793b00, so I'm not ignoring you, is that they have already been fixed 😄 |
Yes, yes, I only saw them after submitting my review 👍🏼 |
|
@jamesturner246 @alexdewar @HarmonicReflux @TinyMarsh , I'm merging so we can include it in the newsletter, but feel free to still review and suggest amendments, if any. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is based on the presentation and tutorial I gave the other day as part of the ReCoDe project and summarises, at a high level, best practices when using version control and online repositories in a collaborative development environment.
Close #80