Contributing Guide

<type>(<scope>): <description> [Priority]

feat(auth): add certificate authentication [P1]
fix(ui): resolve dark mode contrast issue [P1]
docs: update ARCHITECTURE.md with cache patterns [P2]
refactor(services): extract common pagination helper [P3]
test(core): add unit tests for ProfileService [P2]

## Summary
Brief description of what this PR does and why.

## Changes
- Bullet list of specific modifications
- Each change on its own line
- Link to related issues if applicable

## Test Plan
- [ ] `dotnet build` - no errors/warnings
- [ ] `dotnet test` - all tests pass
- [ ] Manual testing: describe steps taken
- [ ] Specific scenarios verified

## Breaking Changes
If any breaking changes exist:
- Describe what breaks
- Provide migration path
- Update CHANGELOG.md

## Documentation
- [ ] Updated relevant documentation
- [ ] Added code comments where needed
- [ ] Updated CHANGELOG.md if user-facing

namespace Intune.Commander.Desktop.ViewModels;

public partial class MyViewModel : ObservableObject
{
    [ObservableProperty]
    private string _displayName = string.Empty;
    
    [RelayCommand]
    private async Task LoadDataAsync()
    {
        // Implementation
    }
}

public async Task<List<SomeType>> ListItemsAsync(
    CancellationToken cancellationToken = default)
{
    var result = new List<SomeType>();

    var response = await _graphClient.SomeEndpoint
        .GetAsync(req => req.QueryParameters.Top = 200, cancellationToken);

    while (response != null)
    {
        if (response.Value != null)
            result.AddRange(response.Value);

        if (!string.IsNullOrEmpty(response.OdataNextLink))
        {
            response = await _graphClient.SomeEndpoint
                .WithUrl(response.OdataNextLink)
                .GetAsync(cancellationToken: cancellationToken);
        }
        else
        {
            break;
        }
    }

    return result;
}

// ❌ BAD - blocks UI thread
var result = SomeAsyncMethod().Result;

// ✅ GOOD - async all the way
var result = await SomeAsyncMethod();

// ✅ GOOD - fire and forget for non-blocking loads
_ = LoadDataAsync();

public interface ISomeService
{
    Task<List<SomeType>> ListAsync(CancellationToken cancellationToken = default);
    Task<SomeType?> GetByIdAsync(string id, CancellationToken cancellationToken = default);
    Task<SomeType> CreateAsync(SomeType item, CancellationToken cancellationToken = default);
    Task<SomeType> UpdateAsync(SomeType item, CancellationToken cancellationToken = default);
    Task DeleteAsync(string id, CancellationToken cancellationToken = default);
    Task<List<Assignment>> GetAssignmentsAsync(string id, CancellationToken cancellationToken = default);
}

public class SomeService : ISomeService
{
    private readonly GraphServiceClient _graphClient;

    public SomeService(GraphServiceClient graphClient)
    {
        _graphClient = graphClient;
    }

    // Implementation with manual pagination on List methods
}

[Fact]
public async Task MethodName_Scenario_ExpectedBehavior()
{
    // Arrange
    var service = new SomeService(mockClient);

    // Act
    var result = await service.SomeMethodAsync();

    // Assert
    Assert.NotNull(result);
}

// Return values
svc.MethodAsync(Arg.Any<T>(), Arg.Any<CancellationToken>())
   .Returns(Task.FromResult(result));

// Argument capture
T? captured = null;
svc.MethodAsync(Arg.Do<T>(x => captured = x), Arg.Any<CancellationToken>())
   .Returns(Task.FromResult(result));
Assert.NotNull(captured);

// Call verification
await svc.Received(1).MethodAsync(expectedArg, Arg.Any<CancellationToken>());

// No-call assertion
svc.DidNotReceive().MethodAsync(Arg.Any<string>(), Arg.Any<CancellationToken>());

[Trait("Category", "Integration")]
public class SomeServiceIntegrationTests : GraphIntegrationTestBase
{
    [Fact]
    public async Task SomeMethod_ReturnsData()
    {
        if (ShouldSkip()) return; // Graceful skip if no credentials
        
        var service = new SomeService(GraphClient);
        var result = await service.SomeMethodAsync();
        
        Assert.NotNull(result);
    }
}

[Trait("Category", "Integration")]

/// <summary>
/// Gets a device configuration by ID.
/// </summary>
/// <param name="id">The configuration ID.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The configuration, or null if not found.</returns>
public async Task<DeviceConfiguration?> GetDeviceConfigurationAsync(
    string id, 
    CancellationToken cancellationToken = default)
{
    // Implementation
}

git checkout main
git pull
git checkout -b feature/my-feature

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

Optional longer explanation.

Fixes #123

feat(auth): add support for client certificate authentication
fix(ui): resolve navigation bug when switching profiles
test(services): add coverage for CacheService edge cases

# Push your branch
git push -u origin feature/my-feature

# Create PR with gh CLI
gh pr create --title "feat(auth): add certificate auth [P2]" --body "$(cat <<'EOF'
## Summary
Adds support for client certificate authentication.

## Changes
- Implemented ClientCertificateCredential support
- Added certificate selection UI
- Updated ProfileService schema

## Test Plan
- [x] dotnet build - no errors
- [x] dotnet test - all tests pass
- [x] Manual testing with certificate

## Documentation
- [x] Updated ARCHITECTURE.md
- [x] Added XML doc comments
EOF
)"