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.
  • As you work on your branch and it starts growing too large in scope and size, strongly consider creating “stacked pull requests” by making a new branch on your current working branch and submit a new pull request on top of the parent pull request branch.
  • In the pull request description, try to explain why you made the changes in the pull request, rather than the what.
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/add-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.