Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
124 lines (91 loc) · 4.58 KB

CONTRIBUTING.md

File metadata and controls

124 lines (91 loc) · 4.58 KB
Raw

Contributing to dynwinrt

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Development Setup

Prerequisites

  • Rust (stable, 2024 edition)
  • Windows 10/11 with Windows SDK installed
  • Node.js 18+ for the JavaScript binding and generated JavaScript tests
  • CPython 3.11–3.14 plus maturin for the Python binding
  • libffi (bundled via the libffi crate)

Some suites also require Windows App SDK metadata/runtime assets or Microsoft.Windows.SDK.Win32Metadata; the test scripts skip optional suites unless those inputs are explicitly required.

Building

# Build the core library
cargo build -p dynwinrt

# Build the code generator
cargo build -p dynwinrt-codegen

# Build the JavaScript binding
(cd bindings/js && npm install && npm run build)

# Build/install the Python binding
(cd bindings/py && python -m maturin develop)

Running Tests

# Core library tests
cargo test -p dynwinrt

# Code generator tests
cargo test -p dynwinrt-codegen

# JavaScript tests
(cd bindings/js && npm test)

# Python tests
(cd bindings/py && python -m pytest)

# End-to-end tests (auto-detects available metadata)
pwsh -File ./tests/e2e/e2e_test.ps1

Coverage

Install the Rust coverage tool once:

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov --version 0.8.7 --locked

Run the mixed-language coverage pipeline:

.\eng\coverage\coverage.ps1

The script builds instrumented Python and Node native modules, runs the Rust/Python/JavaScript tests and E2E suite, and writes HTML, LCOV, XML, and JSON reports under artifacts\coverage. Default line gates are Rust 45%, Python 70%, and JavaScript 18%; override them with the -Min*LineCoverage parameters, or re-check the percentage gates in an existing report tree without rerunning tests via -ValidateOnly.

Report generation also requires executed Rust lines in each JavaScript native binding module winrt_types.rs, winrt_methods.rs, value.rs, winrt_array.rs, winrt_struct.rs, js_storage.rs, and com_value.rs under bindings/js/src, plus bindings/py/src/runtime.rs. The wiring-only JavaScript lib.rs need not appear in LCOV. E2E coverage additionally requires the JavaScript and Python native WinRT implementation adapters and the core winrt_implementation source family. Missing or unexecuted required sources fail independently of the percentage gates; hits in another source or language cannot replace them. Run .\eng\coverage\coverage.threshold.tests.ps1 for the source-guard and threshold boundary regression tests without building native modules.

JavaScript coverage includes the runtime and the complete generated WinRT, implementation, and Classic COM E2E fixture trees, including unexecuted files. Tests that generate bindings in unrelated temporary directories do not cover these measured fixtures. Extend the existing E2E runner checks when adding projected paths: the temp-folder storage case compares collection interface aliases with canonical calls and checks native query pagination and cancellation without requiring indexing, network access, or UI.

Code Style

  • Run cargo clippy before submitting PRs
  • Run cargo fmt --all to format code; CI enforces cargo fmt --all -- --check
  • Follow standard Rust conventions

Filing Issues

Use the GitHub issue tracker to report bugs or request features. Please use the provided issue templates when available.

Pull Requests

  1. Fork the repo and create your branch from main
  2. If you've added code, add tests that cover the new functionality
  3. Ensure the relevant Rust and language-binding tests pass
  4. Run cargo clippy and address any warnings
  5. Submit your pull request

Thank you for contributing!