Skip to content

Workflow

Issue-Driven Development

  • Check existing issues before starting work: glab issue list
  • Open an issue for new features or bugs before writing code
  • Reference the issue number from your merge request
# List and search issues
glab issue list
glab issue list --label "Priority::High"

# Create an issue
glab issue create --title "..." --description "..." --label "Type::Bug,Priority::Medium"

Labels follow a Type::* / Priority::* / Effort::* scheme — check glab label list before inventing a new one.

Branching

Create a branch (ideally via git worktree) per issue or feature, with a descriptive name:

git worktree add ../worktrees/feat-new-feature -b feat-new-feature
cd ../worktrees/feat-new-feature

# ... make changes, running tests frequently ...
task test:unit

# Before committing
task test:ci

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Examples:

feat(backup): add progress display for large transfers
fix(gear): resolve SSH connection timeout issue
docs(contributing): update development workflow
test(cli): add error scenario coverage

Use a scope where it helps (e.g. fix(config): handle missing TOML sections); add ! after type/scope for breaking changes.

Merge Requests

glab mr create --title "feat: description" --description "Closes #<issue-number>"

# Check CI status before requesting review
glab ci status --branch <branch>

Before opening an MR:

  • task test:ci passes locally
  • Tests added/updated for the change
  • Documentation updated if behavior changed
  • Commit messages follow Conventional Commits

MR description: clear title, detailed description, and Closes #<issue-number> so the issue auto-closes on merge.

Code Review

As a contributor:

  • Keep changes focused and atomic
  • Respond to review comments promptly
  • Keep commit history clean (rebase rather than merge-commit noise, where reasonable)

As a reviewer:

  • Focus on correctness and maintainability, not personal style preferences
  • Confirm CI passes and coverage isn't regressing
  • Verify documentation was updated where the change warrants it

Common Development Tasks

Adding a new CLI command

  1. Add the command function in src/fnb/cli.py, using shared options from src/fnb/options.py
  2. Add the business logic in the appropriate module (fetcher.py, backuper.py, etc.)
  3. Write tests covering success and failure paths
  4. Update the relevant docs page under docs/usage/

Adding a configuration option

  1. Update the Pydantic models in src/fnb/config.py
  2. Add validation logic and tests for it
  3. Update docs/usage/configuration.md and examples/ configs

Fixing a bug

  1. Write a test that reproduces the bug first
  2. Fix the bug
  3. Confirm the test passes and add a regression test if the existing suite didn't catch it
  4. Update documentation if the fix changes documented behavior