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 page.

When creating branches and pull requests, follow these general guidelines:

  • Create branches following the Conventional Branches 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.
TipCreating 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 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 style. Use the 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.
TipWriting 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 for the Conventional Commits extension.

Workflow helper

We use some tools to help automate some of the tasks of working on the project repositories, such as formatting/linting Markdown and Python code or re-building a website or software. They are all found in the justfile file. Using justfile requires opening a Terminal, and how you do that depends on the application you are using.

If you don’t know what any of this means, ask the Team Lead or another member, and we will help you out.

If you use VS Code, you can run this command by using Ctrl/Cmd-Shift-P to access the Command Palette, then type out “terminal create new”, and finally hit enter. A Terminal will open up in VS Code. You can also type out “terminal focus” and select the option “Terminal: Focus on Terminal View”, which will switch your cursor to the Terminal on the bottom.

In the Terminal, type out just and hit Enter to see a list of commands you can use for helping you develop the project and work better together in a team. Read the descriptions for each of the commands to identify which ones you want or need to use. For instance, if you need to reformat your code or Markdown, or build the website locally, all of these commands are found in the justfile.

Writing Python code

While writing Python code, follow these guidelines:

  • Use Ruff as well as the VS Code Python and Ruff extension linters/formatters (should work automatically) to check that the format of code is written correctly by follow the styling instructions. For instance:
    • 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:

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"

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)

When writing documentation, we write in Quarto Markdown (.qmd) files. See the Quarto documentation for more information on how to write Markdown.

To format the Markdown files, as we aim to do before committing our changes, we use VS Code. To format a Quarto file, follow these steps:

  1. Open the Command Palette in VS Code by pressing Ctrl/Cmd-Shift-P.
  2. Type “Visual Mode” and select the option that appears (“Quarto: Edit in Visual Mode”).
  3. In Visual Mode, save the file (Ctrl/Cmd-S). This will format the file.
  4. To go back to the Source Mode (the default mode), open the Command Palette again, type “Source Mode”, and select the option that appears (“Quarto: Edit in Source mode”).
  5. Now, you’re ready to commit your changes.

Alternatively, use Ctrl/Cmd-Shift-F4 keybinding to switch to Visual Mode, then use the same keybind to switch back to Source Mode.