docs: add tip on conventional commit extension for vs code

entries/git-workflow-guidelines/branching.md

@@ -45,7 +45,7 @@ When you create a branch, it's important to give the branch a short, descriptive
 | Bugfix | For fixing a bug | bugfix/(short-description) | bugfix/fix-data-cleaning-error |
 | Feature | For adding, removing, or modifying a feature* | feature/(short-description) | feature/add-variance-plot |
 | Hotfix | For quickly fixing critical issues, usually with a temporary solution | hotfix/(short-description) | hotfix/fix-select-button |
-| Doc | For writing, updating, or fixing documentation | doc/(short-description) | doc/git-guidelines |
+| Docs | For writing, updating, or fixing documentation | docs/(short-description) | docs/git-guidelines |
 
 In the table above, (short-description) in the "Pattern" column is a short phrase, concisely describing the work done on the branch. Examples of short descriptions could be *fix-data-cleaning-error*, *add-variance-plot*, *fix-recursive-loop*, or *init-git-entry*. As with file naming, we use the [kebab-case](https://www.tuple.nl/knowledge-base/kebab-case) naming convention. :warning: not written anywhere why we do it or that we do it. Should we add a decision post on this somewhere? :warning:
 
@@ -57,7 +57,7 @@ Elaborating on the use cases of each type of branch:
 
 If you want your branch to refer to a specific issue, this can also be included in the branch name. For example, the branch name "feature/30-optimise-data-load-with-parquets" shows that the work on this branch includes a feature related to issue 30 which optimised the data loading process with parquets (which is a column-oriented data storage format)
 
-In addition, some teams include author initials in the branch names to keep track of developers' work, e.g., feature/skb-add-variance-plot.
+In addition, some teams include author initials in the branch names to keep track of developers' work, e.g., feature/skb-add-variance-plot. :warning: do we want to do that? :warning:
 
 These naming practices will help you avoid bad practices such as using numbers only and long branch names, as well as support consistency. Consistency in branch naming is important, so whenever you have chosen a convention, stick to it throughout the project to avoid confusion.
 
@@ -141,3 +141,5 @@ The naming scheme presented in this post is inspired by the following posts:
 - | Topic | topic/(id)-(short-description) | topic/456-query-optimization |
 - | Release | release/(release-id) | release/2021-04-13 |
 - | Support | support/(id)-(short-description) | support/876-app-support-reboot-fix |
+- test for experimenting something which is not an issue
+- wip for a work in progress

entries/git-workflow-guidelines/commits.md

@@ -144,6 +144,8 @@ See below for resources on how to use the command line and VS Code for committin
 
 If you use VS Code, see their posts [Introduction to Git in VS Code](https://code.visualstudio.com/docs/sourcecontrol/intro-to-git) and [Using Git source control in VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview).
 
+If you want to follow the Conventional Commits convention, the VS Code extension *Conventional Commits* eases the process. To see how this extension works in VS Code, go to [this video](https://www.youtube.com/watch?v=lwGcnDgwmFc).
+
 ### Using the command line
 
 GitHub's [Git Guides](https://github.com/git-guides/git-commit) go through the different steps of committing using the command line.

entries/git-workflow-guidelines/index.md

@@ -7,28 +7,24 @@ date: last-modified
 
 ### Introduction
 
-When using Git in a collaborative setting, there are several workflow conventions to choose from. For the Seedcase project, we want to make explicit how we work with Git to ensure a more homogeneous and clear structure across contributions. This includes how and when we create *branches*, *pull requests*,
-*reviews*, *issues*, and *commits*, as well as naming conventions for all of the above.
+Note: In this and the following Git workflow posts, we assume that you know the basics of what Git is. If this is not the case, the Git-scm website includes great documentation, videos to get you started, as well as cheat sheets. (from VS code post)
+Otherwise, we will briefly introduce Git below.
 
-In short, we follow the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow), a simple Git workflow for collaboration, which will be explained below. See the [GitHub flow decision post](../why-github-flow/index.md) for why we made this decision.
+When using Git in a collaborative setting, there are several workflow conventions to choose from. For the Seedcase project, we want to make explicit how we work with Git to ensure a more homogeneous and clear structure across contributions. This includes how and when we create *branches*, *pull requests*, *reviews*, *issues*, and *commits*, as well as naming conventions for all of the above.
+
+In short, we encourage the practice of the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow), a simple, yet structured, Git workflow suitable for smaller teams and parallel developmet. See the [GitHub flow decision post](../why-github-flow/index.md) for why we made this decision.
 
 In this post, we will go through the practices of the GitHub flow and clarify the conventions we follow. This is meant as guidelines for streamlining how we work together so we, as a team, can collaborate more effortless and efficiently across repositories.
 
 Remember that this is all a learning process. It takes time to get these practices under the belt, so they are a seamless part of you workflow. So don't be too hard on yourself (and your collaborators), when these guidelines aren't followed :o)
 
 --- issue templates, in another post? "Furthermore, we have implemented a couple of issue templates to follow."
 
-### Introduction to Branches (is this too basic? / should we remove this?)
-
-In Git, a branch is a separate line of development that allows you to work on a feature, bug fix, or other code changes without affecting the main branch of your repository. When the work is complete, the changes can be merged to the main branch. Branches are essential for collaborative software development, and they serve several purposes:
+### What is Git?
 
-- **Isolating Changes and Parallel Development**: Branches provide isolation for different features or bug fixes. Each branch represents a specific task or development effort, allowing multiple developers to work on different parts of a project simultaneously without interfering with each other's code. This speeds up development and reduces conflicts that may arise when multiple people modify the same code simultaneously.
-- **Testing and Experimentation**: You can create branches to experiment with new features or changes without affecting the main project. This is useful for testing ideas or implementing potentially disruptive changes before deciding whether to merge them into the main codebase.
-- **Bug Fixing**: When a bug is discovered in the main branch, you can create a branch specifically to fix that bug. Once the fix is ready, it can be merged back into the main branch.
+https://github.com/git-guides
 
-Overall, branches facilitate collaboration among team members by allowing them to work on their individual branches and then merge their changes into the main branch when they're ready. Once you've completed your work in a branch and tested it thoroughly, you can merge it back into the main branch through a pull request (PR). Branches are a fundamental concept in Git and GitHub, and they play a crucial role in managing code changes and ensuring a smooth and organised development workflow.
-
-For a more thorough, general introduction to branches, see the [Git Documentation Book](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches).
+This could also be the place for explaining how Git tracks files and local vs. remote repositories?
 
 ### Branching Strategy: GitHub Flow
 
@@ -53,17 +49,26 @@ There are a few points about this kind of workflow, we would like to emphasise:
 - **Collaboration happens in the PRs**: Better work is created when you are not working in a silo. During PRs, you'll have a conversations about the proposed changes and your collaborators might have some ideas for improvement. PRs is a chance to utilise each other's experiences and expertise
 - **The change does not have to be fully implemented before creating a PR**: When you create a PR, you communicate to your collaborators what you are working on. In this [talk](https://www.youtube.com/watch?v=vCwuZfK0VG4), it is recommended to create your PRs early and not wait until your work is complete, for two reasons: 1) it helps prevent that someone else does not start doing the same work as you are currently working on, and 2) you can start the discussion of the changes you are currently implementing. Remember to mark the PR as a [draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft), if it's still a work in progress.
 
+- When a developer should branch? From where?
+- When they should merge (and how often)? To where?
+
+Following the GitHub flow, branches should be created whenever a developer wants to make changes or add something new to the codebase. They will create the new branch from the main branch. Aim for shorter living branches - e.g., max two weeks? Idk. but be specific!
+
+Before a branch can be merged, it needs to be reviewed and approved by a collaborator. In this way, new or edited code or documentation will only be merged into the main branch after review and the main branch will contain deployable code and documentation.
+
 ## Overview of Git Workflow Guideline Entries
 
-1. [Branching](branches.md)
+**Disclaimer**: With software development comes a lot of creative freedom. There is not one *best* way to do things. The same goes for working with Git. We have tried to collect what we believe to be good practices when working with Git. However, don't worry too much about how you will have to implement all of these recommendations into your practices. You might be able to incorporate some of them into your development process naturally, with practice. However, each can actually be applied iteratively after you have written your code (if need be). ???
+
+1. [Branching](branching.md)
 2. [Commits](commits.md)
 3. [Pull requests](prs.md)
 4. [Issues](issues.md)
 5. ... Maybe: GitHub actions (automating workflows) + unit testing (maybe even test development guidelines?)?
 
 ### Git workflows in practice ... remove/move?
 
-If you like to use the Terminal, the [Git documentation](https://git-scm.com/docs) contins thorough description of git commands.
+If you like to use the Terminal, the [Git documentation](https://git-scm.com/docs) contains thorough description of git commands.
 If you prefer not to use the Terminal, GitHub has great [Documentation](https://docs.github.com/en).
 
 ## Automatic workflows (CI pipeline?) ... remove/move?

entries/git-workflow-guidelines/issues.md

@@ -13,7 +13,7 @@ This post will introduce the notion of issues on GitHub as well as guidelines on
 
 In [GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues#), issues are described as a way to track ideas, feedback, tasks, or bugs for work on GitHub.
 
-Since issues are a part of GitHub, they are well-documented in GitHub's documentation. Go to the [Quickstart for GitHub Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart) post for an introduction to what they are and how to open a blank issue and filling in information.
+Since issues are a part of GitHub, they are well-documented in GitHub's documentation. Go to the [Quick start for GitHub Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart) post for an introduction to what they are and how to open a blank issue and filling in information.
 
 ## Cross-reference
 
@@ -25,7 +25,7 @@ You can find information on linking an issue and a pull request in [Linking a pu
 
 ## Issue Templates
 
-One way to structure an issue is in the form of a [user story](https://www.atlassian.com/agile/project-management/user-stories). This structure helps with 1) keeping the user in mind, 2) explicitly stating the functionality of the change requested, and 3) how this will benefit the user, when writing the issue.
+One way to structure an issue is in the form of a [user story](https://www.atlassian.com/agile/project-management/user-stories). When writing the issue, this structure helps with explicitly 1) keeping the user in mind, 2) explicitly stating the functionality of the change requested, and 3) how this will benefit this kind of user.
 
 The structure is like so:
 

entries/git-workflow-guidelines/prs.md

@@ -5,6 +5,19 @@ date: last-modified
 
 {{< include /includes/_wip.qmd >}}
 
+## Introduction to Pull Requests
+
+:yellow_circle: and facilitate collaboration among team members by allowing them to work on their individual branches and then merge their changes into the main branch when they're ready. Once you've completed your work in a branch and tested it thoroughly, you can merge it back into the main branch through a pull request (PR).:yellow_circle:
+
+## Creating a Pull Request (Checklist)?
+
+- Naming (see below)
+- Description
+- Assign assignee and reviewer
+  - Assignee: Assignee means you own the pull request or issue and are getting it into a merge-ready state. If you are no longer owning a given pull request or issue, take your name off as assignee.
+  - Reviewer: Reviewer means you are actively reviewing a pull request.
+- Is it still a draft?
+
 ## Pull Request Naming
 
 Pull requests (PRs) are proposed changes from one branch to another. However, they are more than just changes; they are the start of a discussion
@@ -51,3 +64,7 @@ Summary
 ### Review guidelines
 
 For guidelines on how to review a pr, see the post [Review through pull requests](https://seedcase-project.org/community/guide-entries/reviewing-prs/index.html) <- maybe move that info here instead.
+
+Tip: How to view "Rich diff" in pull requests --> very helpful for html and markdown reviewing!
+
+- Go to "Files changed" and press the "Rich diff" button in the (looks like a document, much like a "Blank document"-button in Word)

entries/why-github-flow/index.md

@@ -183,7 +183,7 @@ REASONS."
 We decided on using the GitHib flow branching strategy because:
 
 1) it is simple and beginner-friendly strategy
-2) it is both well-known and well documented, creating clear guidelines that enable consitency across contributions
+2) it is both well-known and well documented, creating clear guidelines that enable consistency across contributions
 3) it offers clear guidelines on every step of collaborative development, including branching, committing, and review processes
 4) longer-living branches works well with parallel, asynchronous work
 5) the balance between multiple branches and simplicity supports continuous delivery, while maintaining the **structure** from git flow (what do I mean here?)