Skip to content

LBS Foundry Development Workflow

This guide outlines the internal development workflow and best practices for the LBS Foundry team.

Types of Work

Development Activities

  • Bug Fixes - Fix issues and improve stability
  • New Features - Add new functionality and capabilities
  • Documentation - Improve guides, examples, and references
  • Tooling - Enhance development experience and workflows
  • Testing - Add test coverage and improve quality
  • Refactoring - Improve code structure and maintainability

Getting Started

1. Development Environment

Follow our Getting Started Guide to set up your development environment.

2. Work Assignment

  • Linear cards - All work must be tracked in Linear
  • Sprint planning - Check current sprint priorities with the team
  • New ideas - Discuss in the development channel before starting

3. Before You Start

  • Discuss larger changes in the development channel first
  • Check existing Linear cards to avoid duplicate work
  • Read relevant documentation to understand the area you're working on
  • Ensure you have a Linear card assigned to you for the work

Linear Integration

We use Linear for project management and issue tracking. All development work must be linked to Linear cards.

Linear Workflow

  1. Get assigned to a Linear card (LBS-XXX format)
  2. Create branch with Linear card number: LBS-123
  3. Reference Linear card in commits when relevant
  4. Include Linear card(s) in PR title: LBS-123: description or LBS-123,LBS-124: description
  5. Link Linear cards in PR description using keywords:
  6. Closes LBS-123 - Automatically closes card when PR is merged
  7. Related: LBS-124 - Links to related cards
  8. Partially addresses: LBS-125 - Shows partial progress

Linear Card States

  • Backlog → Todo → In Progress → In Review → Done
  • Move card to In Progress when you start working
  • Move to In Review when you create a PR
  • Card automatically moves to Done when PR is merged (if using Closes LBS-XXX)

Multiple Linear Cards

For work spanning multiple cards: - Branch: Use primary card number: LBS-123 - PR Title: Include all cards: LBS-123,LBS-124: description - PR Description: List all cards with appropriate keywords

Development Workflow

1. Sync with Main Branch

# Ensure you're on the latest main branch
git checkout main
git pull origin main

2. Create a Feature Branch

Always use the Linear card number as your branch name:

# Create branch with Linear card number
git checkout -b LBS-123

# For different cards
git checkout -b LBS-456
git checkout -b LBS-789

Branch Naming Convention: - Use the Linear card number: LBS-XXX - For multiple cards, use the primary card number: LBS-123

3. Make Your Changes

Follow our coding standards:

Backend (.NET/C#)

  • Use this. prefix for all member access
  • Follow established naming conventions
  • Add [RequiresRoles] attributes for security
  • Include comprehensive unit tests
  • Follow event sourcing patterns

Frontend (Svelte/TypeScript)

  • Use TypeScript for type safety
  • Follow Svelte/SvelteKit best practices
  • Use existing component patterns
  • Include proper error handling
  • Add appropriate tests

4. Test Your Changes

# Run the full test suite (xUnit v3 — use `dotnet run`, not `dotnet test`)
dotnet run --project src/Tests/LBS.UnitTests/LBS.UnitTests.csproj

# Build to ensure no compilation errors
dotnet build LBS.slnx

# For frontend changes (from repo root)
pnpm web:build

5. Commit Your Changes

Write clear, descriptive commit messages:

# Examples of good commit messages
git commit -m "add player statistics query endpoint"
git commit -m "fix authorization issue in command executor"
git commit -m "update getting started guide for new developers"
git commit -m "add integration tests for user management"

# Reference Linear cards when relevant
git commit -m "implement player team integration (LBS-123)"
git commit -m "fix memory leak in data harvester (LBS-456)"

Commit Message Guidelines: - Use clear, descriptive language - Start with a verb in present tense - Reference Linear cards when relevant: (LBS-123) - Keep the first line under 50 characters - Add detailed explanation in body if needed

6. Push and Create Pull Request

# Push your branch (Linear card number)
git push origin LBS-123

# Create a pull request on GitHub
# Use the provided PR template

Pull Request Guidelines

PR Title

Always include Linear card numbers in the PR title: 

LBS-123: add real-time player statistics dashboard
LBS-456: resolve memory leak in data harvester  
LBS-789: improve security configuration guide

# Multiple Linear cards
LBS-123,LBS-124: implement player team integration

PR Description

Use our PR template to include: - Summary of changes made - Type of change (feature, bugfix, etc.) - Testing performed - Breaking changes (if any) - Linear card references - Include all related Linear cards: 

## Linear Cards
- Closes LBS-123
- Related: LBS-124, LBS-125
- Partially addresses: LBS-126

PR Checklist

  • [ ] Code follows our style guidelines
  • [ ] Self-review completed
  • [ ] Comments added for complex logic
  • [ ] Tests added/updated and passing
  • [ ] Documentation updated if needed
  • [ ] No breaking changes (or properly documented)
  • [ ] Security considerations addressed
  • [ ] Linear card number(s) included in PR title
  • [ ] All related Linear cards referenced in description
  • [ ] Branch name is Linear card number (LBS-XXX)
  • [ ] Mermaid ERD updated if contracts, events, or builders were added/changed (ERD file)

Testing Requirements

Required Tests

  • Unit tests for new business logic
  • Integration tests for API endpoints
  • Security tests for authorization features
  • Performance tests for critical paths

Test Patterns

// Command tests with authorization
[Test]
public async Task CreatePlayer_WithValidRole_ShouldSucceed()
{
    using (AuthorizationTestHelpers.SetTestUser(RoleDefinition.Member))
    {
        var command = new CreatePlayerCommand { /* ... */ };
        var events = await this.commandExecutor.ExecuteAsync(command, 0);
        events.Should().HaveCount(1);
    }
}

// Query tests with security
[Test]
public async Task PlayerQuery_WithoutAuth_ShouldReturnEmpty()
{
    using (AuthorizationTestHelpers.SetAnonymousUser())
    {
        var query = new PlayerSearchQuery { /* ... */ };
        var (results, count) = await this.queryService.ExecuteAsync(query);
        results.Should().BeEmpty();
    }
}

Security Guidelines

Authorization

  • Always add [RequiresRoles] to new commands and secure queries
  • Test authorization scenarios in your tests
  • Follow principle of least privilege when assigning roles
  • Use system context only for legitimate internal operations

Data Protection

  • Never log sensitive information (passwords, tokens, PII)
  • Validate all inputs at command/query boundaries
  • Use parameterized queries to prevent injection
  • Follow OWASP guidelines for web security

Documentation Standards

Code Documentation

/// <summary>
/// Creates a new player with the specified details.
/// This command requires Member role or higher.
/// </summary>
/// <param name="command">The player creation command</param>
/// <returns>Domain events representing the player creation</returns>
[RequiresRoles(RoleDefinition.Member)]
public async Task<IReadOnlyList<IDomainEvent>> CreatePlayerAsync(CreatePlayerCommand command)

API Documentation

  • OpenAPI/Swagger documentation is auto-generated
  • Add meaningful descriptions to endpoints
  • Include example requests/responses
  • Document error conditions

Architecture Documentation

  • Update ADRs for significant architectural changes
  • Document new patterns in developer guides
  • Keep architecture diagrams current
  • Explain complex business logic

What NOT to Contribute

Avoid These Changes

  • Breaking changes without team discussion
  • Dependencies without approval (security implications)
  • Configuration changes that affect production
  • Large refactoring without prior agreement
  • Code style changes mixed with functional changes

Security No-nos

  • Hardcoded secrets or credentials
  • Disabled security features
  • Unauthenticated endpoints (unless explicitly public)
  • Personal/test data in commits

Code Review Process

What to Expect

  1. Automated checks run on your PR
  2. Team member review within 1-2 business days
  3. Feedback and discussion if changes needed
  4. Approval and merge once ready

Review Criteria

  • Functionality - Does it work as intended?
  • Security - Is it properly authorized and secure?
  • Performance - Will it scale appropriately?
  • Maintainability - Is the code clean and understandable?
  • Testing - Is it adequately tested?
  • Documentation - Is it properly documented?

Addressing Feedback

  • Be responsive to reviewer comments
  • Ask questions if feedback is unclear
  • Make requested changes promptly
  • Push additional commits (don't force push during review)
  • Resolve conversations when addressed

Team Excellence

Development Best Practices

  • Consistent quality in your work
  • Helpful code reviews for team members
  • Documentation improvements that benefit everyone
  • Mentoring newer team members
  • Initiative in identifying and solving problems
  • Knowledge sharing in team meetings and channels

Getting Help

When You're Stuck

  • Development channel - Ask questions and get quick help
  • Documentation - Check our comprehensive guides
  • Pair programming - Work with experienced team members
  • Code exploration - Study existing patterns and implementations

Common Questions

Summary

Following this workflow ensures consistency, quality, and maintainability across the LBS Foundry platform. Whether you're fixing a small bug, adding a major feature, or improving documentation, these practices help the entire team work effectively.

Ready to start? Review our Getting Started Guide and check Linear for your assigned cards.

Questions about the workflow? Ask in the development channel or reach out to a senior team member.