Contributing

Thank you for your interest in contributing to 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 win32, what features you’d like, and what works well on GitHub Discussions.
• 📢 Share 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 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.5 or higher
• 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 win32 to your local machine:

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

📦 Installing Dependencies​

Navigate to the project directory and install dependencies:

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 win32 package, follow these steps:

1. Navigate to the package directory:

   Terminal

   cd packages\win32
   

2. Run the tests with the following command:

   Terminal

   dart test -j 1 --test-randomize-ordering-seed=random
   
   • -j 1: Runs tests sequentially, increasing the likelihood of detecting segmentation faults or similar test failures.
   • --test-randomize-ordering-seed=random: Randomizes the test execution order to identify unintended dependencies between tests.

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 win32 Itself​

If you want to contribute to the 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 tools\generate.dart script to update the library files:

  Terminal

  dart tools\generate.dart
  

• Structs can be auto-generated by including them in the win32_structs.json file and running the tools\generate.dart script, which will generate the corresponding Dart files.

• Constants belong in the constants.dart; please add documentation. In rare cases (where the constant is truly self-documenting), you may add to the constants_nodoc.dart, although the goal is to gradually document more constants.

• 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 tools\generate.dart script to generate the relevant class 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>

Here's an example of a good commit message:

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_generator: Runs tests for package:generator to ensure stability.
  • test_win32: Runs tests for package:win32 to ensure stability.

• 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 win32! 🎉