Skip to content

Latest commit

 

History

History
110 lines (77 loc) · 6.37 KB

CONTRIBUTING.md

File metadata and controls

110 lines (77 loc) · 6.37 KB
Raw

Contributing to comtypes

Welcome! 😄

comtypes is a community project for developing a lightweight COM client and server framework coded by pure Python on Windows environments.

We appreciate all contributions, from reporting bugs to implementing new features.

Table of contents

To keep the community healthy and sustainable 👥

If you have to understand all that this package has to offer, it would require an enormous amount of knowledge.

  • Python 🐍
  • C-lang 💻
  • COM interface, implementation, client and server 🚪
  • COM type library functionalities 🔧

However, there is no means to say that you must understand all of these things to be a contributor.

The purpose of this document is to provide a pathway for you to contribute to this community even if you only know a small portion of this package.

Please keep the followings in your mind:

  • 👉 Please follow the following guidelines when posting a GitHub Pull Request or filing a GitHub Issue on this project.
  • 🙇 The community may not be able to process and reply to your issue or PR right-away. Participants in the community have a lot of work to do besides comtypes, but they would try their best.
  • 📖 For code of conduct, please read Contributor Covenant.

Reporting bugs 🐛

We use GitHub issues to track bugs and suggested enhancements. You can report a bug by opening a new issue.

We need several infomations for breaking troubles down.

This package handles functionalities of COM libraries in the user's environment.
Therefore, even if a community participant would like to work on a solution to a problem, the COM library may not be available in their development environments.
Also, it is possible that you can only reproduce this in your own environment.
If the community requests you to "try do-something", please respond to them.

At least, please write the following.

Environment data

  • OS:
  • Python version:
  • comtypes version:
  • what COM type libraries you want to use:

Code snippet

  • Please provide a minimal, self-contained code snippet that reproduces the issue.
  • GitHub permalink is very useful as references.

Situation reproducing steps

  • Please provide a minimal description of conditions and steps needed to reproduce the situation.

Expected behavior

  • The results what you wanted.

Actual behavior

  • The results what you got.

Suggesting enhancements ✨

We use GitHub issues to track bugs and suggested enhancements. You can suggest an enhancement by opening a new issue. Before creating an enhancement suggestion, please check that a similar issue does not already exist.

Please describe the behavior you want and why, and provide examples of how comtypes would be used if your feature were added.

Contributing to the codebase 📂

Picking an issue

Pick an issue by going through the issue tracker and finding an issue you would like to work on. Feel free to pick any issue that is not already assigned. We use the help wanted label to indicate issues that are high on our wishlist.

If you are a first time contributor, you might want to look for issues labeled good first issue.
The comtypes code base is quite complex, so starting with a small issue will help you find your way around!

If you would like to take on an issue, please comment on the issue to let others know. You may use the issue to discuss possible solutions.

Setting up your local environment

Install a version of Python supported by comtypes into your Windows environment.
Start by forking the comtypes repository, then clone your forked repository using git.

Working on developments

Create a new git branch in your local repository, and start coding!

Tests can be run with python -m unittest discover -v -s ./comtypes/test -t comtypes\test command.

When comtypes.client.GetModule is called, it parses the COM library, generates .py files under .../comtypes/gen/..., imports and returns Python modules.
Those .py files act like ”caches”.

If there are some problems with the developing code base, partial or non-executable modules might be created in .../comtypes/gen/....
Importing them will cause some error.
If that happens, you should run python -m comtypes.clear_cache to clear those caches.
The command will delete the entire .../comtypes/gen directory.
Importing comtypes.client will restore the directory and __init__.py file.

Pull requests

When you have resolved your issue, open a pull request in the comtypes repository.
Please include the issue number on the PR comment.
When enough PRs have been accepted to resolve the issue, please close the issue or mention it to the person(s) involved.

Contributing to documentation 📚

Documents are in the .../docs directory.

Follow the same steps as in the codebase for contributions.

Final words 💚

Thank you very much for your contributions!
Hope that your contribution will be more profitable for your project and for the work of the community participants.