feat: Extend tutorial to include basic explanations of how to use git…

Basic-tutorial.md

@@ -1,32 +1,88 @@
-## 1. Starter resources
-In the rest of this tutorial we will assume some basic knowledge on how committing, pushing, and branching works. Some good resources are:
-* [W3Schools](https://www.w3schools.com/git/default.asp?remote=github)
-* [Webtuu](https://webtuu.com/blog/04/git-basics-branching-merging-push-to-github)
-* [Rogerdudler](https://rogerdudler.github.io/git-guide/)
+## Motivation
+The reason this workflow is important is because it allows you to share your work with others as well as making sure it is reusable and maintainable. Git makes sure others can use your work in less than thirty seconds without you even sending an email or any files. This ensures you can keep track of what has been done and how. This also means you can easily revert changes. Let's say you added something new to your project like extra analysis for a new dataset and it seems to work as expected but later you find out this change has broken a different part of your code. Now you can roll back those changes to get back to working code.
 
-Please note that these tutorials are as general as possible so they use a lot of terminal commands. It is very likely that you will be working with a text editor/IDE such as Visual studio/PyCharm/others which often are integrated with github and have greatly simplified all steps. In this case take a brief look at one of the links above to get an idea of how the git system works and then look up the "(program you'll be using) + git" and you will find a very easy way to work with it.
 
-## 2. When and why do I even do all of this?
-### The why
-The reason this workflow is important is because it allows you to share your work with others as well as making sure it is reusable and maintainable. Git makes sure others can use your work in less than thirty seconds without you even sending an email or any files. Things such as commits, braching, continuous integration (quality control), makes sure you can keep track of what has been done and how. This also means you can easily revert changes. Let's say for example you added something new to your project like extra analysis for a new dataset and it seems to work okay but later you find out this change has broken a different part of your code. Now you can easily find where the problem is and roll back those changes to get back to working code.
+## 1. Downloading git
 
-### The when
+Git is the application that powers services such as Github and Gitlab. It is essential for sharing and storing code. For the rest of this tutorial you will need to have a working installation of git which can be downloaded [here](https://git-scm.com/). If you have downloaded and installed this we can get started. Do quickly verify whether git was installed correctly by typing `git --version` in the _command line interface_ (CLI) of your operating system. For MacOS, this would be terminal; for Windows, it's called command prompt. Then, press the Enter key on your keyboard. If Git was installed correctly you should get a response like "Git version 2.49.0"
+
+NOTE: Installing Git by itself is not necessary if you want to work with Github Desktop (which is recommended) as it also installs Git automatically.
+
+
+## 2. Downloading Github Desktop
+
+This application provides a nice visual interface for interacting with Github. It is highly recommended for beginners as it means you don't have to use the command line. It can be downloaded [here](https://desktop.github.com/download/). After installation it is important that you authenticate yourself. This can be done by going into settings, then accounts, and then signing into Github. If you do not have a github account yet please create one.
+
+After that you should see something like this:
+![Github desktop homescreen](/images/homescreen.png)
+
+It is of course also possible to use the more traditional command-line interface. We recommend a visual interface for people who are unfamiliar with Git and just starting out. Should you nonetheless want to use CLI instead we recommend the following resource: [Git CLI tutorial](https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line)
+
+## 3. Creating a new repository
+
+### What is a repository?
+Your research project, including code, data and documentation, is stored in what's called a repository. It is important to note here that you will have a local repository and a remote repository. The remote one is the one that is hosted on Github and the local one only exists on your device. If you have made any changes to the project  on your device, these are now part of your local repository and by "pushing" these to the remote repository, you can update the remote repository. Now others can acces the updated code as well. They can "pull" these changes so that their local repository reflects the up-to-date version and the reverse also applies if other collaborators make changes. 
+
+### How to start?
+When you're starting a new project, there are a couple of scenarios:
+1. You are starting a new and blank project.
+2. Somebody else has started the project, hosted its remote repository on GitHub, and shared it with you.
+3. You have started the project on your device but haven't pushed it to Github.
+
+This is how to proceed depending on the scenario
+
+1. In this case you can simply click "Create a New Repository" in Github Desktop. If you are doing a general data analysis project we recommend you use our [template](https://github.com/sodascience/research-project-boilerplate).
+2. In this case you have to "clone" that repository. This just means setting up the local repository based on the remote repository. If you go to the homepage of that repository on Github there should be a green button which displays a link when clicked. You should copy this link. Then you can go to Github desktop and click clone repository and paste the link. After that Github Desktop takes care of the rest of the setup.
+<img src="images/cloneImage.png" width="400">
+
+3. In this case you can click on "Add Local Repository" after which you will have to select the folder containing your current version of the project. If this already happened to contain a .git file the rest happens automatically, if it didn't you simply click "create a repository here instead"
+
+NOTE: Pushing to github does not necessarily publish your code so that it is visible for everyone to see. You can set your repository to private if you want to have control over who sees your code/data.
+
+## 4. Making changes
+When making changes it is important to understand two concepts, the first being <em>commits</em>. Let's say you have made a certain change to some code. The project is now different. What you then do is save the new version of the project by "committing" it. Over time the history then looks as follows:
+
+<img src="images/basicCommits.png" width="400">
+
+Of course just numbering the versions doesn't convey a lot of information. Probably we should give our versions more useful names such as:
+
+<img src="images/betterNamesCommits.png" width="400">
+
+When you want to commit you can see the changes in Github Desktop and see the commit button down below with the option to add a message to the new version. Once committed it is saved. You can then also "push" it so the new version is available for possible collaborators on Github. 
+
+![Changes](/images/changes.png)
+
+The second concept is <em>branches</em>. Branches are a way to keep two (temporarily) distinct versions of the project.What we have seen with commits so far has been on a single branch. Multiple branches looks as follows: 
+
+<img src="images/basicbranch.png" width="400">
+
+
+ When working with other people you can each work on your own version (branch) of the project without interfering with each other's work. You can create a new branch by clicking on "current branch" and then clicking "new branch". You can also recombine these branches if you want to merge the separate changes you and your collaborator made. This is done through a PR (Pull Request) which graphically looks as follows: 
+
+ <img src="images/pullRequest.png" width="500">
+
+ You can create a PR by going to your repository on github, clicking "Pull requests", and then "New pull request"
+
+
+## 5. How/when do I do this committing and branching?
+
+### The flow
 The most basic flow is as follows
 1. You have a project repository and you want to change something (anything really).
-2. You create a new branch where you will change said thing. (A branch is just a copy of the project)
+2. You create a new branch where you will change said thing.
 3. You make some changes and you commit and push these. Likely this will happen multiple times as this change consists of multiple smaller changes.
 4. You have changed what you wanted to change so you create a PR. 
 5. You click merge.
 6. You are done.
 
 This of course leaves a couple of questions unanswered, namely:
-* How do I even get a repository, do I need to create a branch to add this?
-* I need names for these commits and branchese, what do I call them?
-* What is a smaller change and can be a commit and what needs its own branch? 
-* How do I do a PR?
-
-Which we will answer in detail below
-* You create a repository by going to github and clicking on the new icon. Once this is done you have your remote repo. That is to say the one that is published on github. Upon creating this Github gives you the option whether to push existing work to there or to simply clone the repo to your local computer. Depending on whether you already have work you should take one of these options.
-* It often helps to give them appropriate names. For example if you've added an extra feature be that analysis or an extra button you would like to indicate that this commit/branch added an extra feature. However if you just fixed an existing problem you want the name to clearly convey that as well. This is why best practices have been developed which can be found in the Github guidelines file.
-* This is a question even seasoned developers struggle with. General advice here would be that once you start working on some change (feature/fix/chore anything really) and you are working on that branch to only have commits that are in direct service to that change. If it is something that you encounter which is not directly linked but you want to fix it is probably best to first finish the existing change and then move on to that task. This helps keep branches focussed.
-* In an ideal scenario no other changes have been made since you started working on a branch and you have people that are also working on the project and can review the changes you've made and give an honest assesment of the quality of the code. In the case that other changes have been made you probably have merge conflicts. In this case you first need to merge main into your branch and resolve conflicts locally after which you can merge still. If there is no one to review your PR you must do this yourself, in this case be honest about the quality of the code and whether there are still improvements that need to be made before it can be merged to main.
+1. I need summary and description for these commits, what do I put there?
+2. What do I name my branches?
+3. What is a smaller change and can be a commit and what needs its own branch? 
+4. How do I do a PR?
+
+Which we answer below:
+1. It often helps to describe clearly what you've done. Start off with "fix:" for example when correcting a typo. If this was in a readme the summary would then read "fix: correct typo in readme". There are different ways to start the summary depending on what type of task you did. An overview can be found in the [Guidelines](GitHub-guidelines-draft.md#Commit-Message-Standard). The description is useful when you did something complex as it gives the opportunity to explain why you made certain choices in your new version.
+2. This depends on the purpose of the branch. If you are adding an extra feature you would want to call it something else compared to when you do a bugfix. The exact naming conventions can be found in the [Guidelines](GitHub-guidelines-draft.md#Branching-Strategy) document.
+2. This is a question even seasoned developers struggle with. General advice here would be that once you start working on some change (feature/fix/chore anything really), and you are working on that branch, to only have commits that are in direct service to that change. If it is something that you encounter which is not directly linked, but you want to fix it, it is probably best to first finish the existing change and then move on to that task. This helps keep branches focussed.
+3. If you or a collaborator has made changes on a branch you can start a PR on Github by going to "pull requests" and then clicking on "New pull request". In an ideal scenario no other changes have been made since you started working on a branch and you have people that are also working on the project. These people can then review the changes you've made and give an honest assessment of the quality of the code. In the case that other changes have been made you probably have merge conflicts. In this case you first need to merge main into your branch and resolve conflicts locally after which you can merge still. If there is no one to review your PR you must do this yourself. In this case be honest about the quality of the code and whether there are still improvements that need to be made before it can be merged to main.

GitHub-guidelines-draft.md

@@ -53,7 +53,6 @@ my-package/
 ├── README.md
 └── pyproject.toml
 ```
-TODO: INSTRUCTION TO CREATE DIFFERENT TYPES OF PROJECT
 
 ### Research / Analysis Project
 
@@ -78,6 +77,8 @@ my-research-project/
 
 ---
 
+NOTE: For this type of project we have a template which follows the recommended project structure and makes the setup a bit easier. It can be found [here](https://github.com/sodascience/research-project-boilerplate).
+
 ## 3. Branching Strategy
 
 ### Default: GitHub Flow (Recommended for most projects)
@@ -267,11 +268,13 @@ Periodically (every few months) review all open issues and close those that are
 
 ## 7. Recommendations for new repositories
 
+### Topics
+When on the homepage of your repository you can click on the settings icon in the about section to add topics to a repository. This is useful as people can easily find out what your project is about. For example if you are using an LLM to analyze CBS data in Python you would use the "cbs" "llm" and "python" tags. Please add these as it makes the purpose of a repository much more clear. Standard convention here is to use lowercase and only to use abbreviations when the abbreviation is generally used more than the full version.
 ### Tests
 
-TODO: Expand this section.
+When developing a tool that others will hopefully use someday it is important to make sure it works as intended. Therefore testing your code to verify this is the case is very useful. It has the additional benefit of being an automatic check whether or not a new change breaks some existing core functionality.
 
-It is important for all new repositories to have tests that are executed by CI and test the functionality of the code every time there is a PR to the 'main' branch. 
+Thus, it is important for all new repositories to have tests that are executed by CI and test the functionality of the code every time there is a PR to the 'main' branch wherever reasonable. If the project is mostly data analysis or is not intended to be reusable this may not apply. This is however a case of author discretion.
 
 Structure of the `tests` directory: