# Contributing to TroubleScout

Thank you for your interest in contributing to TroubleScout! This document provides guidelines and information to help you contribute effectively.

## 🔒 Branch Protection Policy

The `main` branch is protected to maintain code quality and stability. All changes must go through a pull request process.

### Protected Branch Rules

The following protections are enforced on the `main` branch:

1. **No Direct Commits**: All changes must be made through pull requests
2. **Required Reviews**: Pull requests require at least one approval from a code owner
3. **Required Status Checks**: The following checks must pass before merging:
   - ✅ Build and Test workflow
   - ✅ Tests workflow (Windows and Ubuntu)
   - ✅ Branch Protection validation workflow
4. **Branch Must Be Up-to-Date**: PRs must be updated with the latest main branch before merging
5. **Signed Commits**: Commits should be signed when possible (recommended)

### Branch Naming Convention

Branch names must follow this pattern:

```text
{type}/{description}
```

`description` should be lowercase and may include letters, numbers, `-`, `_`, `.`, or `/`.

**Valid types:**

- `feature/` - New features or enhancements
- `fix/` - Bug fixes
- `hotfix/` - Critical production fixes
- `docs/` - Documentation changes
- `test/` - Test additions or modifications
- `refactor/` - Code refactoring
- `perf/` - Performance improvements
- `ci/` - CI/CD changes
- `build/` - Build system changes
- `chore/` - Maintenance tasks

**Examples:**

- `feature/add-disk-diagnostics`
- `fix/memory-leak-in-session`
- `fix/release-1.2.8`
- `docs/update-installation-guide`

### Commit Message Format

All commit messages must follow one of these formats:

#### Option 1: Emoji Prefix (Preferred)

```text
{emoji} {Summary of changes}

Example: ✨ Add WinRM connectivity check
```

#### Option 2: Conventional Commits

```text
{type}({scope}): {summary}

Example: feat(diagnostics): add WinRM connectivity check
```

#### Option 3: Simple Plan Commits (for workflow tracking)

```text
Initial plan
WIP
Work in progress
Checkpoint

Note: These are allowed for initial planning commits but should be avoided in final PRs.
```

#### Option 4: Automated Updates (for bots and automated tools)

```text
Update {filename}
Update {description}

Example: Update README.md
Example: Update dependencies

Note: These are typically generated by bots or automated tools (e.g., Dependabot, Copilot).
```

**Common Emojis:**

- ✨ `:sparkles:` - New features
- 🐛 `:bug:` - Bug fixes
- 📝 `:memo:` - Documentation
- ♻️ `:recycle:` - Refactoring
- ⚡️ `:zap:` - Performance improvements
- 🔒 `:lock:` - Security fixes
- ✅ `:white_check_mark:` - Tests
- 🔧 `:wrench:` - Configuration
- 🚀 `:rocket:` - Deployment/releases
- 🔖 `:bookmark:` - Version tags

## 📋 Pull Request Process

### Before Opening a PR

1. **Create a branch** following the naming convention
2. **Make your changes** with clear, focused commits
3. **Test locally**:

   ```bash
   dotnet build
   dotnet test
   ```

4. **Ensure code quality**:
   - Follow existing code style
   - Add tests for new features
   - Update documentation as needed

### Opening a PR

1. **Title**: Must start with an emoji or conventional commit type
   - Example: `✨ Add network diagnostics tool`
   - Example: `feat: add network diagnostics tool`

2. **Description**: Include:

   - What changes were made
   - Why the changes were needed
   - How to test the changes
   - Any breaking changes or migration notes

3. **Link Issues**: Reference any related issues with `Closes #123` or `Fixes #123`

### PR Review Process

1. **Automated Checks**: Wait for all CI checks to pass
2. **Code Review**: A code owner will review your changes
3. **Address Feedback**: Make requested changes and push new commits
4. **Approval**: Once approved and all checks pass, a maintainer will merge

### After Merge

- Your branch will be automatically deleted
- Changes will be included in the next release

## 🚀 Release Process

Releases are automated via GitHub Actions. When a version tag is pushed, the release workflow automatically:

1. Builds a self-contained Windows x64 executable
2. Packages `TroubleScout.exe` and includes `runtimes/` only when runtime files are present
3. Creates a GitHub release with release notes

If `WINGET_TOKEN` and a `winget-pkgs` fork are configured, a separate **Publish to WinGet** workflow also runs after the **Release** workflow completes to open or update the WinGet manifest PR automatically.

For local WinGet checks before or after release publication, use `.\Tools\Validate-WinGetRelease.ps1`. See [RELEASE-PROCESS.md](RELEASE-PROCESS.md) for details.

**Only maintainers can create releases.** See [RELEASE-PROCESS.md](RELEASE-PROCESS.md) for detailed instructions.

## 🧪 Testing Guidelines

### Running Tests

```bash
# Run all tests
dotnet test

# Run tests with detailed output
dotnet test --verbosity normal

# Run tests for specific project
dotnet test TroubleScout.Tests/TroubleScout.Tests.csproj
```

### Writing Tests

- Place tests in the `TroubleScout.Tests` project
- Follow existing test patterns
- Use descriptive test names: `MethodName_Scenario_ExpectedBehavior`
- Include both positive and negative test cases

## 🏗️ Development Setup

### Prerequisites

1. **.NET 10.0 SDK** - [Download](https://dotnet.microsoft.com/download/dotnet/10.0)
2. **GitHub Copilot CLI** - Optional for local source runs without bundled assets. Install/update via:

   [Install Copilot CLI](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli)

3. **On Windows:** PowerShell 6+ (PowerShell 7+ recommended)

4. **Node.js** - Only needed for npm-based Copilot CLI installation - [Download](https://nodejs.org/)

5. **Authentication mode**:
   - GitHub mode: active GitHub Copilot subscription
   - BYOK mode: OpenAI API key (`OPENAI_API_KEY`) and use `--byok-openai`

### Building from Source

```bash
# Clone the repository
git clone https://github.com/sasler/TroubleScout.git
cd TroubleScout

# Restore dependencies
dotnet restore

# Build the project
dotnet build

# Run the application
dotnet run -- --server localhost
```

### Project Structure

```text
TroubleScout/
├── Program.cs                  # CLI entry point
├── TroubleshootingSession.cs   # Copilot SDK integration
├── Services/                   # Infrastructure services
│   ├── PowerShellExecutor.cs   # Command execution
│   └── WinRMConnection.cs      # Remote connectivity
├── Tools/                      # AI tool functions
│   └── DiagnosticTools.cs      # Diagnostic capabilities
├── UI/                         # User interface
│   └── ConsoleUI.cs            # Spectre.Console TUI
└── TroubleScout.Tests/         # Unit tests
```

## 📝 Code Style Guidelines

### General Principles

- Follow [C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
- Use meaningful variable and method names
- Keep methods focused and small
- Add XML documentation comments for public APIs
- Handle exceptions appropriately

### PowerShell Integration

- Always validate commands before execution
- Use the safety model (Get-* auto-execute, others require approval)
- Test commands on localhost before remote execution

### Copilot SDK Usage

- Use event-based streaming with `CopilotSession.On()`
- Subscribe to `AssistantMessageDeltaEvent` for streaming
- Wait for `SessionIdleEvent` to detect completion
- Never use async iterators (not supported by SDK)

## 🐛 Reporting Issues

### Bug Reports

Include:

- TroubleScout version
- Operating system and version
- .NET version (`dotnet --version`)
- Steps to reproduce
- Expected vs actual behavior
- Error messages or logs

### Feature Requests

Include:

- Use case description
- Why this feature is needed
- How it should work
- Any examples or mockups

## 🔐 Security

- **Do not commit secrets** or credentials
- **Report security vulnerabilities** privately to the maintainers
- **Follow the security model** when adding new diagnostic tools
- **Validate user input** to prevent command injection

## 📄 License

By contributing, you agree that your contributions will be licensed under the MIT License.

## 💬 Questions?

- Open a [GitHub Discussion](https://github.com/sasler/TroubleScout/discussions)
- Review existing [Issues](https://github.com/sasler/TroubleScout/issues)
- Check the [README](README.md) for documentation

## 🙏 Thank You

Your contributions help make TroubleScout better for everyone. We appreciate your time and effort!