---
title: "Workflow for developing software and documentation"
---

## GitHub and Git

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

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`](https://just.systems/man/en/) 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.


## Writing documentation (`.qmd` files)

When writing documentation, we write in Quarto Markdown (`.qmd`) files.
See the [Quarto
documentation](https://quarto.org/docs/authoring/markdown-basics.html)
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.