refactor: ♻️ move Git and GitHub content into guidebook

how-we-work/workflow.qmd

@@ -4,130 +4,8 @@ title: "Workflow for developing software and documentation"
 
 ## GitHub and Git
 
-When adding or modifying content on either the website or the products
-themselves, we follow the "branch-pull request" workflow. This is
-described in more detail in the [GitHub
-flow](https://docs.github.com/en/get-started/quickstart/github-flow)
-page.
-
-When creating branches and pull requests, follow these general
-guidelines:
-
-- Create branches following the
-  [Conventional Branches](https://github.com/pshaddel/conventional-branch)
-  approach by using the VSCode Extension, that is also in our
-  (automatically) recommended extension list (see tip below).
-- When creating branches and pull requests, keep them as focused and
-  specific to the issue as is reasonable and limit how many changes are
-  made in that pull request. The fewer changes made in a pull request,
-  the easier and faster it is for reviewers to look it over, make
-  suggestions, and merge it in.
-- After creating a pull request, add it to the relevant GitHub Project
-  since this is where we keep an overview of what each of us is
-  currently working on.
-- In the pull request description, try to explain *why* you made the
-  changes in the pull request, rather than the *what*.
-
-::: callout-tip
-### Creating conventional branches using the VS Code extension
-
-#### What are conventional branches?
-
-For naming branches, we follow a naming scheme called **conventional
-branches**. Conventional branches are a way of naming branches that are
-easy to read and understand. This naming follow a specific format that
-includes a type and a branch description. Specifically, the format of a
-conventional branch name is `<type>/<branch>`, where `<type>` is the
-type of the branch and `<branch>` is a short description of the change
-that will be made. The description should be written in imperative mood
-using kebab-case. For example `feat/new-feature` or `fix/bug-fix`.
-
-#### Using the VS Code extension
-
-To ease the process of creating conventional branches, we use the VS
-Code extension "Conventional Branches" by pshaddel. This extension
-provides autocompletion for conventional branch names and can help you
-create branches that follow the conventional branches format. This
-extension is in our recommended extensions and should automatically pop
-up to install when you're using VS code to edit any of the Seedcase
-GitHub repositories. If for some reason, it doesn't pop up, you can
-install the extension by searching for "Conventional Branches" in the
-Extensions view in VS Code.
-
-To use the extension, follow these steps:
-
-- Make sure you have the "Conventional Branches" extension installed in
-  VS Code.
-- Open the Command Palette in VS Code by pressing `Ctrl/Cmd-Shift-P`.
-- Type "Conventional Branches" and select the option that appears.
-- Follow the steps that appears to create a conventional branch name.
-  The extension will provide auto-completion for the type of the branch
-  name, and it will help you create a branch name that follows the
-  conventional branches format.
-
-For more information, see the
-[documentation](https://marketplace.visualstudio.com/items?itemName=pshaddel.conventional-branch)
-for the Conventional Branch extension.
-:::
-
-When writing commits, follow these general guidelines:
-
-- Keep changes to files per commit as small as is reasonable and as
-  specific as possible. For example, if making edits to the same file
-  path across multiple files, include all those files in one commit that
-  includes only that change to the file path.
-- Write commit messages following the
-  [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
-  style. Use the
-  [Conventional commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits)
-  VS Code extension included in our (automatically) recommended
-  extensions to help you write these messages.
-- Write commit messages focusing on the *why* more than the *what*,
-  though this isn't always possible.
-
-::: callout-tip
-### Writing conventional commits using the VS Code extension
-
-#### What are conventional commits?
-
-Conventional commits are a way of writing commit messages that are easy
-to read and understand. They follow a specific format that includes a
-type, a scope, and a message. The type is a word that describes the kind
-of change that was made, such as "feat" for a new feature or "fix" for a
-bug fix. The scope is a word that describes the part of the codebase
-that was changed, such as "docs" for documentation or "ui" for the user
-interface. The message is a short description of the change that was
-made.
-
-#### Using the VS Code extension
-
-To ease the process of writing conventional commits, we use the VS Code
-extension "Conventional Commits" by vivaxy. This extension provides
-autocompletion for conventional commit messages and can help you write
-messages that follow the conventional commits format. This extension is
-in our recommended extensions and should automatically pop up, when
-you're using VS code to edit any of the Seedcase GitHub repositories. If
-for some reason, it doesn't pop up, you can install the extension by
-searching for "Conventional Commits" in the Extensions view in VS Code.
-
-To use the extension, follow these steps:
-
-- Make sure you have the "Conventional Commits" extension installed in
-  VS Code.
-- Stage the changes you want to commit, e.g., in the Source Control view
-  in VS Code or using a Terminal.
-- Open the Command Palette in VS Code by pressing `Ctrl/Cmd-Shift-P`.
-- Type "Conventional Commits" or just "commit" and select the option
-  that appears for Conventional Commits.
-- Follow the steps that appear to write a conventional commit message.
-  The extension will provide auto-completion for the type of commit
-  message, and it will help you write a message that follows the
-  conventional commits format.
-
-For more information, see the
-[documentation](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits)
-for the Conventional Commits extension.
-:::
+Our guidelines for how to work with Git and GitHub can be found in
+[our guidebook](https://guidebook.seedcase-project.org/workflows/commits).
 
 ## Workflow helper
 
@@ -165,41 +43,6 @@ While writing Python code, follow these guidelines:
   - Write docstrings for every function, class, and method.
   - Include type hints for both inputs and returns.
 
-## Creating pull requests
-
-### Stacking pull requests
-
-A stacked pull request is when one pull request has been opened to merge
-into the `main` branch and then another pull request is opened to merge
-into that first pull request. See the diagram below for a visual
-representation of this:
-
-```{mermaid}
-gitGraph
-    commit
-    branch first-pull-request
-    checkout first-pull-request
-    commit
-    branch second-pull-request
-    checkout second-pull-request
-    commit
-    checkout first-pull-request
-    merge second-pull-request id: "merge commit"
-    checkout main
-    merge first-pull-request id: "squash merge"
-```
-
-::: {.callout-important}
-In our current workflow, we prefer to avoid stacked pull requests unless
-under exceptional circumstances. Instead, if a PR depends on changes in
-another PR, these can either be duplicated in both PRs if the change is
-very small, or left just in the one of the PR with a comment that
-clearly indicates which PR to merge first. Duplicating changes can be
-useful when the change is small and it also ensures that both PRs can
-build and pass checks. Generally though, leaving some changes in just
-one PR is sufficient when it is enough for reviewers to just see the
-diff on GitHub to review efficiently.
-:::
 
 ## Writing documentation (`.qmd` files)