Contributing

Thank you for your interest in contributing to package:win32!

This guide provides everything you need to get started and make your contributions effective and rewarding.

We strive to maintain a welcoming and inclusive community, so please read our Code of Conduct before contributing.

📝 Good to Know​

• Working on Issues: If you'd like to work on an existing issue, please comment on the issue page to let others know before you begin.
• Proposing New Features: Have an idea for a new feature? Create an issue to discuss it with the community and maintainers before diving in.

🙌 How You Can Contribute​

• 🌟 Star Us on GitHub: If you enjoy using this package, a star on GitHub helps support our work.
• 🐛 Report Bugs: Found a bug? Let us know on our GitHub Issues page.
• 📝 Improve Documentation: High-quality documentation is crucial. Help us improve it by refining the existing docs or adding new content.
• 💬 Give Feedback: Share your experience using package:win32, what features you'd like, and what works well on GitHub Discussions.
• 📢 Share package:win32: Spread the word about this project to reach more users.
• 💻 Contribute to the Codebase: Work on new features or tackle open issues — all contributions are highly appreciated!
• 📦 Share Your Own Packages: If you've created a package that builds on top of package:win32 and provides a more Dart-friendly API for a specific Windows API, please share it with us! Our community is growing rapidly, and your package could be useful for many people. We'll be happy to add your package to our packages page and share it with our community.

🛠️ Setting Up the Environment​

⚙️ Requirements​

• Dart version 3.11 or higher
• Melos for managing the monorepo
• git-cliff for generating changelogs
• Lefthook for managing Git hooks

If you're planning to contribute to the documentation, you'll also need:

• Node.js version 20 or higher
• npm version 10 or higher

Once your environment is ready, fork the repository, clone it locally, and set up the project.

📥 Cloning the Repository​

Clone your fork of package:win32 to your local machine:

git clone https://github.com/<your-username>/win32.git

📦 Installing Dependencies​

Navigate to the project directory and first activate package:melos globally, then install the dependencies:

dart pub global activate melos
dart pub get

🧩 Setting Up Git Hooks​

This project uses Lefthook to manage Git hooks. Install the hooks by running the following in the project root:

lefthook install

This will set up checks that automatically ensure code quality and consistency before commits.

🧪 Running Tests​

To run tests for the package:win32, run the following command:

melos run test:win32

We require tests for each feature or bug fix. If you're unsure how to write tests for your changes, feel free to ask on the relevant GitHub issue page.

📝 Contributing to the Documentation​

Our documentation is built with Docusaurus. To contribute to the documentation, you need to install the dependencies and start the development server:

> cd website
> npm install
> npm start

Now, head over localhost:3000 to see the documentation.

💻 Contributing to the package:win32 Itself​

If you want to contribute to the package:win32 itself, follow the steps below:

Classic Win32 APIs​

• When wrapping a Win32 API, use the Unicode ('W') wide variants of these APIs, rather than the ANSI ('A') variants. For example: CredWriteW, rather than CredWriteA.

• To create a new API, don't edit the main library files themselves; these get overwritten. Instead, edit the win32_functions.json file and run the melos run generate command to generate the library files:

  Terminal

  melos run generate
  

• Constants can be auto-generated by including them in the win32_constants.json file and running the melos run generate command, which will generate the corresponding Dart files.

• Structs can be auto-generated by including them in the win32_structs.json file and running the melos run generate command, which will generate the corresponding Dart files.

• There are plenty of good existing patterns to build off in these locations; try to mirror an existing function if you can for consistency!

• Ideally pull requests for new API submissions include a sample (examples\ directory) and some tests (packages\win32\test\ directory).

COM APIs​

Begin by editing the com_types.json file, specifying the desired COM interface, and then run the melos run generate command to generate the relevant classes in the packages\win32\lib\src\com directory.

🚀 Committing Your Work and Preparing a Pull Request​

To maintain a consistent and clean codebase, we enforce coding standards and use tools to ensure high-quality contributions.

🎨 Coding Style​

Please follow the Dart style guide to keep the codebase clean and consistent.

📜 Commit Convention​

We use Conventional Commits to structure our commit messages for clarity and uniformity.

Please use the following format for commit messages:

<type>(optional scope): <description>

Examples:

• feat: add DragQueryFile API
• fix: resolve an issue with the PROPVARIANT struct

Commit messages are validated with a GitHub action, so be sure to use the correct format when making a pull request.

🧩 Git Hooks​

The following hooks run automatically with Lefthook:

• Pre-Commit Hooks:

  • analyze: Checks code for style issues.
  • format: Formats code according to Dart guidelines.
  • test_ffi_leak_tracker: Runs tests for package:ffi_leak_tracker
  • test_filepicker_windows: Runs tests for package:filepicker_windows
  • test_generator: Runs tests for package:generator
  • test_win32: Runs tests for package:win32
  • test_win32_clipboard: Runs tests for package:win32_clipboard
  • test_win32_gamepad: Runs tests for package:win32_gamepad
  • test_win32_registry: Runs tests for package:win32_registry
  • test_win32_runner: Runs tests for package:win32_runner
  • test_winmd: Runs tests for package:winmd

• Commit-msg Hook:

  • check_commit: Ensures the commit message follows Conventional Commits

🔄 Creating a Pull Request​

After committing your changes, push them to your fork and create a pull request. When you open a pull request, tests will run automatically, and our maintainers will review it.

Please use the pull request template to provide details about your changes, ensuring a smoother review process.

Thank you for contributing to package:win32! 🎉