Contributing

Contributing

Thank you for your interest in contributing to Purview Telemetry Source Generator!

Development Setup

Prerequisites

• .NET 10 SDK (pinned via global.json)
• Bun — for package management and build scripts
• just — command runner

Quick Start

git clone https://github.com/kjldev/purview-telemetry-sourcegenerator
cd purview-telemetry-sourcegenerator
bun install
just build
just test

Common Commands

Command	Description
just build	Build the source generator and integration tests
just test	Run the 282 integration tests
just format	Format code according to .editorconfig rules
just changeset	Create a changeset for your changes
just changeset-status	Show pending changesets

Making Changes

1. Fork the repository and create a feature branch
2. Make your changes
3. Run just format && just build && just test to verify
4. If your change affects users (new feature, bug fix, deprecation), run just changeset to describe it
5. Open a PR to main

Changeset Requirement

Every PR that changes user-facing behaviour must include a changeset. A changeset is a small markdown file that describes what changed and what kind of version bump it warrants (patch / minor / major).

Create one with:

just changeset

This opens an interactive prompt — select the bump type and write a one-line summary. The file is committed with your changes.

PRs without a changeset will fail the Changeset Check status check. If your PR genuinely needs no release note (docs-only, CI fixes, dependency bumps), add the skip-changeset label.

Release Process

Releases are fully automated. Once your PR is merged:

1. The changeset bot creates (or updates) a Version Packages PR
2. Merging the Version PR triggers the CD pipeline
3. The pipeline builds, tests, packs, and publishes a GitHub Release with NuGet artifacts

See docs/release-process.md for the full release process guide, including:

• How to set up the bot token (GitHub App / fine-grained PAT / classic PAT)
• GitHub ruleset configuration (branch + tag protection)
• DSC setup scripts for all account scopes (personal, org, enterprise, ghes)
• Immutable releases configuration
• Troubleshooting guide

Integration Tests and Snapshot Testing

Integration tests use Verify for snapshot testing. If your change modifies generated code:

1. Run just test — tests will fail with *.received.* diff files
2. Review the diffs carefully
3. Accept correct snapshots by copying *.received.* → *.verified.* (or use the Verify IDE extension)

Never manually edit *.verified.* files — they are machine-generated only.

Code Style

• C# is formatted with CSharpier — run just format before committing
• Only comment code that needs clarification; avoid noise comments
• Follow existing patterns in the codebase