Skip to main content

Development Workflow

Day-to-day development practices for Almafrica.

Daily Workflow​

1. Start Your Day​

# Pull latest changes
git checkout main
git pull origin main

# Start services
docker-compose -f docker-compose.local.yml up -d

# Start backend
cd backend && dotnet run --project Almafrica.API

# Start web (new terminal)
cd web/almafrica-web && pnpm dev

2. Pick Up Work​

  1. Find an issue on GitHub or project board
  2. Assign yourself
  3. Create a branch
git checkout -b feature/ABC-123-add-export-feature

3. Development Cycle​

# Make changes...
# Test locally...
# Commit frequently with clear messages
git add .
git commit -m "ABC-123: Add export button to farmer list"

Branch Strategy​

Branch Naming​

TypePatternExample
Featurefeature/ABC-123-descriptionfeature/ABC-123-farmer-export
Bug fixfix/ABC-456-descriptionfix/ABC-456-login-crash
Chorechore/descriptionchore/update-dependencies
Docsdocs/descriptiondocs/api-documentation

Branch Flow​

main ─────●─────●─────●─────●─────▶
           \           /
feature/    ●──●──●──●
ABC-123           ↑
               PR merged

Commit Conventions​

Format​

ABC-123: Brief description of change

- Detail point 1
- Detail point 2

# Optional: Related issue
Closes #42

Examples​

# Feature
ABC-123: Add farmer CSV export functionality

# Bug fix
fix: Resolve login timeout on slow connections

# Refactor
refactor: Extract sync logic to separate service

# Documentation
docs: Add API endpoint documentation

Commit Best Practices​

  • Keep commits atomic (one logical change)
  • Write clear, descriptive messages
  • Reference issue numbers when applicable
  • Commit frequently, push when ready

Code Review Process​

Creating a Pull Request​

  1. Push your branch:
git push -u origin feature/ABC-123-description

  1. Create PR on GitHub with:

    • Clear title referencing the issue
    • Description of changes
    • Screenshots for UI changes
    • Test evidence

  2. PR Template Checklist:

    • Tests pass locally
    • Code follows style guidelines
    • Documentation updated
    • No sensitive data exposed

PR Description Template​

## What changed
Brief description of changes

## Why
Business context or problem being solved

## How to test
1. Step 1
2. Step 2

## Screenshots (if applicable)

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated

Reviewing PRs​

  1. Check functionality: Does it work as described?
  2. Check code quality: Is it readable and maintainable?
  3. Check tests: Are edge cases covered?
  4. Check documentation: Is it updated?

Review Feedback​

# Suggestion
**Suggestion:** Consider extracting this to a helper method

# Must fix
**Required:** This will break in production - fix before merge

# Question
**Question:** Why this approach over [alternative]?

Testing​

Backend Tests​

# Run all tests
dotnet test

# Run specific test class
dotnet test --filter "FullyQualifiedName~FarmerServiceTests"

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Web Tests​

# Run unit tests
pnpm test

# Run e2e tests
pnpm test:e2e

# Run with coverage
pnpm test:coverage

Mobile Tests​

# Run unit tests
flutter test

# Run integration tests
flutter test integration_test/

Before Pushing​

Run checks for your affected layer:

Backend Checklist​

dotnet build Almafrica.sln
dotnet test Almafrica.sln

Web Checklist​

pnpm type-check
pnpm lint
pnpm test
pnpm build

Mobile Checklist​

flutter analyze
flutter test

Debugging​

Backend Debugging​

VS Code:

  1. Set breakpoints in code
  2. Press F5 or Run > Start Debugging
  3. Select ".NET Core Launch"

Rider:

  1. Set breakpoints
  2. Click Debug icon
  3. Attach to process

Web Debugging​

  1. Use browser DevTools (F12)
  2. React DevTools extension
  3. console.log / debugger statements

Mobile Debugging​

# Enable debugging
flutter run --debug

# View logs
flutter logs

Hot Reloading​

Backend​

Changes to C# files require restart. Use dotnet watch for automatic restart:

dotnet watch --project Almafrica.API

Web​

Next.js has automatic hot reload. Changes appear instantly.

Mobile​

Flutter supports hot reload. Press r in terminal after saving changes.

Database Changes​

Create Migration​

cd backend

# Create migration
dotnet ef migrations add AddPhoneNumberToFarmer \
  --project Almafrica.Infrastructure \
  --startup-project Almafrica.API

# Apply migration
dotnet ef database update

Important: Always Include Down()​

Every migration must have a working Down() method for rollbacks:

protected override void Down(MigrationBuilder migrationBuilder)
{
    migrationBuilder.DropColumn(
        name: "PhoneNumber",
        table: "Farmers");
}

Useful Commands​

Git​

# Interactive rebase last 3 commits
git rebase -i HEAD~3

# Undo last commit (keep changes)
git reset --soft HEAD~1

# See file history
git log --follow -- path/to/file.cs

Backend​

# List EF migrations
dotnet ef migrations list

# Rollback to specific migration
dotnet ef database update PreviousMigrationName

# Generate migration script
dotnet ef migrations script

Web​

# Clear Next.js cache
rm -rf .next

# Update dependencies
pnpm update

# Check for outdated packages
pnpm outdated

Getting Help​

  1. Check Troubleshooting Guide
  2. Search existing GitHub issues
  3. Ask in team chat (#engineering)
  4. Create a new issue with details