# Contributing to MSTest

Welcome, and thank you for your interest in contributing! Your contributions to open source, large or small, make projects like this possible.

There are many ways to contribute:

- [Submit issues](https://github.com/Microsoft/testfx/issues) and help verify fixes as they are checked in.
- Review the [source code changes](https://github.com/Microsoft/testfx/pulls).
- Contribute to the documentation.

## Creating Issues

- **DO** use a descriptive title that identifies the issue to be addressed or the requested feature.
- **DO** specify a detailed description of the issue or requested feature.
- **DO** provide the following for bug reports
  - Describe the expected behavior and the actual behavior. If it is not self-evident such as in the case of a crash, explain why the expected behavior is expected.
  - Provide example code that reproduces the issue.
  - Specify any relevant exception messages and stack traces.
- **DO** subscribe to notifications for the created issue in case there are any follow-up questions.

## Submitting Pull Requests

- **DO** ensure submissions pass all Azure DevOps legs and are merge conflict-free.
- **DO** follow the [.editorconfig](http://editorconfig.org/) settings for each directory.
- **DO NOT** submit Pull Requests without having an approved feature request or enhancement.
- **DO NOT** submit large code formatting changes without discussing them with the team first.

## Coding Style

The MSTest project follows the same rules as the runtime repository [developer guide](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/coding-style.md).
The repository includes [.editorconfig](http://editorconfig.org) files to help enforce this convention.
Contributors should ensure they follow these guidelines when making submissions.

## TODO Comment Policy

To keep technical debt visible and tracked, the project enforces the following policy for `TODO` comments in code:

- **DO** reference a GitHub issue in every `TODO` comment (e.g., `// TODO(#1234): Refactor this once the new API is available`).
- **DO** convert any `TODO` that does not warrant a tracking issue into a regular comment that explains the rationale.
- **DO NOT** leave `TODO` comments without an associated GitHub issue link. These should be caught during code review.

## Developing

Please see our [Dev Guide](./docs/dev-guide.md) which explains how to develop, build, and test.

## Agentic Workflows

This repository ships a large number of AI-powered GitHub Actions workflows authored with [GitHub Agentic Workflows (`gh aw`)](https://github.com/github/gh-aw). The full catalog, conventions, and quick-start commands live in [`.github/workflows/README.md`](./.github/workflows/README.md).

A few rules worth knowing before you touch anything under `.github/workflows/`:

- **DO** treat the `*.md` file as the source of truth. The companion `*.lock.yml` is generated by `gh aw compile`.
- **DO** run `gh aw compile <workflow-id>` after editing an agentic workflow source (or any `shared/*.md` it imports) and commit the regenerated `*.lock.yml` in the same change.
- **DO** keep strict mode enabled. When in doubt, pass `--strict` to `gh aw compile` to enforce action pinning, network policy, safe-output usage, and other security defaults across all workflows.
- **DO NOT** hand-edit `*.lock.yml`, or any generated dependency manifest that `gh aw compile` may emit under `.github/workflows/` (`package.json`, `requirements.txt`, `go.mod`, …). They are all regenerated by `gh aw compile`.
- **DO NOT** set `strict: false` in workflow frontmatter.
