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.

If your task is too large in scope, modifies or adds many new files, or has several complicated pieces, strongly consider making “stacked pull requests”. A stacked pull request is a pull request that is made on top of another pull request. This way, you can separate the changes into smaller, more manageable pieces that can be reviewed more easily and quickly since larger pull requests take longer and are more difficult to review. When making Stacked pull requests, follow these general guidelines:

  • When making the first, base pull request, write in the description that this will be a stacked pull request so that no one should merge it, only until all the stacked pull requests are ready.
  • As each stacked pull request is ready for review, team members will review and make suggestions as needed. As the author, you’ll need to make sure all suggestions are merged downstream to the later pull requests by rebasing.
  • Once all stacked pull requests are reviewed and approved, they will all be rebased onto the base pull request before being finally squashed into the base pull request. This way, the base pull request will contain all the changes from the stacked pull requests.
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 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.
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 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 start Docker, 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:

mainfirst-pull-requestsecond-pull-request0-b067c181-9115d5c2-52dacb0merge commitsquash merge

Stacking pull requests are useful when the task we are working on is fairly large or modifies many files in different ways. We want to keep pull requests small enough to be easily reviewed, as a pull request’s change gets larger, it becomes increasingly harder to review. So to keep each stacked pull request small while ensuring that the final pull request is atomic and “squashable”.

Stacked pull requests are not without challenges. So, when stacking pull requests, we aim to follow these guidelines:

  1. Firstly, as much as possible, avoid stacking pull requests.
  2. If a stacked pull request is necessary, then clearly communicate that it will be a stacked pull request in the description by clearly writing that this is a stacked pull request and linking to the relevant pull request(s).
  3. Then, a team member with merge permissions will hold off merging until all development has finished in the stacked pull requests.
  4. As requests for changes come in, it is the responsibility of the pull request author to rebase the changes to later pull requests in the stack.

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.