Contributing

Thank you for your interest in contributing to our project. We value your input and appreciate your effort to improve our work. This guide will help you get started with contributing to the win32.

We adhere to a Code of Conduct to ensure a welcoming and inclusive community. Please read it before contributing.

🙌 Ways You Can Contribute​

• 🌟 Star Us on GitHub: If you enjoy using our package, don't forget to star us on GitHub! Your support means a lot.
• 🐛 Report Bugs: If you find a bug, please report it on our GitHub Issues page. We'll do our best to fix it as soon as possible.
• 📚 Improve Documentation: Good documentation is imperative to the success of any project. You can help us by improving the quality of our documentation or adding new content.
• 📝 Give Feedback: We're always looking for ways to make win32 better. Please share how you use win32, what features are missing, and what works well via GitHub Discussions.
• 📢 Share win32: Help us reach more people. Share the win32 repo with anyone who might be interested.
• 💻 Contribute to the Codebase: Your help is needed to make this project the best it can be! You can develop new features or fix existing issues. Every contribution is greatly 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​

If your environment is ready, you can fork the win32 repository and clone it to your local machine.

📥 Cloning the Repository​

After you fork the win32 repository, you need to clone it to your local machine. Instead of using the halildurmus/win32 repository, it's recommended to use your fork. This way, you can push your changes to your fork and create a pull request from there.

git clone https://github.com/halildurmus/win32.git

📦 Installing Dependencies​

After you clone the repository, you need to install the dependencies:

dart pub get

✅ Running Tests​

You can use the dart test command to run tests for the package:win32:

dart test

📝 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 execute the tools\generate.cmd script to update the library files:

  Terminal

  tools\generate.cmd
  

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

  Once generated, compile the struct_sizes.cpp on a 64-bit machine architecture, typically using the Visual Studio Developer Command Prompt with the following command (replace xxxxx with the installed Windows SDK build):

  Terminal

  cl /I "C:\Program Files (x86)\Windows Kits\10\Include\10.0.xxxxx.0\winrt" \
    tools\struct_sizes\struct_sizes.cpp
  

  Once compiled, run the resulting struct_sizes.exe file located in the project root to obtain struct sizes; copy the output directly into the structSizeMap within the struct_sizes.dart file, and finally, execute the tools\generate.cmd script to generate struct size tests for each struct.

• 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 execute the tools\generate.cmd script to generate the relevant class in the packages\win32\lib\src\com directory.

🚀 Committing Your Work and Preparing a Pull Request​

win32 is a monorepo with multiple packages and examples. To ensure we keep things clean and in order, we use several tools to enforce a good development experience.

🎨 Coding Style​

We follow the Dart style guide to maintain a clean and consistent codebase. Make sure you adhere to the style guide when working on the codebase.

📜 Commit Convention​

Commit messages are essential for clarity in our development process. We use Conventional Commits to keep our commit messages consistent and easy to understand.

We expect commit messages to follow this format:

<type>(optional scope): <description>

Here's an example of a good commit message:

feat: add `refCount` function

🔄 Creating a Pull Request​

After you commit your changes, you can push your changes to your fork and create a pull request. When you create a pull request, a GitHub action will run tests. Our maintainers will review your changes shortly and merge your pull request if everything is in order.

Our Pull Request template is designed to ensure you provide all the necessary information about your changes. Please make sure you fill out the template with the required information.

We look forward to seeing your contributions! 🎉