.. _contributing_index: Contributing ============ Contributions to Patcher are encouraged and welcomed. Contributing does not *have* to mean writing Python code! Project documentation can always be improved and `feature requests `_ can be submitted for new ideas or functionality. We, the developers of this tool, **firmly believe** that diverse backgrounds strengthen a product. Therefore, we encourage you to share your ideas and thoughts, regardless of your programming experience. Some topics we are hoping to develop in future versions of Patcher are: - **Support for other MDM vendors**; Implementing functionality for other MDM vendors (such as Kandji) - **Windows compatibility**; whether via Docker container or additional windows-specific credential libraries - **Patch analyzation**; providing information on which patch titles may need TLC above others (e.g., titles that have been released longer than 'x' amount of time that have active CVEs) - **Installomator support**; identifying which patch titles have an `Installomator `_ label available to assist Admins in setting up automatic patching. How to Contribute ----------------- First and foremost, get in touch! Ideally, this would be done by submitting a feature request (for introducing new functionality) or an issue if something is not working as expected. Although this is not required, it is *greatly appreciated*. Pull Requests ^^^^^^^^^^^^^ We recommend following the typical `GitHub workflow `_: - `Fork `_ the Patcher repository - Clone the repository locally in the directory of your choosing - Create a feature branch that roughly describes the changes implemented (i.e., ``kandji`` if introducing functionality with Kandji) - Work through code review .. important:: Be sure to pull any changes from the ``main`` branch before submitting a pull request. All pull requests should be made against the ``main`` branch of the repository. The pull request will be reviewed by project maintainers, and must pass the pytest unit tests before it is merged. Unit tests can be found in the `tests `_ directory in the repository. Tests are triggered automatically by a GitHub action which can be found in the `pytest.yml `_ file. Environment Setup ----------------- Patcher uses both ``ruff`` and ``black`` to format and lint code before any changes are merged to main. The ``Makefile`` document included with the repository assists in automating this process on your behalf. Settings for both ``black`` and ``ruff`` can be found in the `pyproject.toml `_ file for reference. Virtual Environment ^^^^^^^^^^^^^^^^^^^ After forking the repository, create and activate a virtual environment with the following command: .. code-block:: console $ python3 -m venv venv && source venv/bin/activate .. dropdown:: Virtual Environment Reference :color: info :icon: code For more information on creating virtual environments, reference `the python packaging guide `_ Makefile commands ^^^^^^^^^^^^^^^^^ .. note:: Be sure to install the ``Xcode Command Line Tools`` in order to use the ``make`` command. With the virtual environment (``venv``) activated, execute the command ``make install``. This will ensure all project dependencies (including development dependencies) are installed properly. Other command options available are: ``uninstall`` Uninstalls all project dependencies. .. warning:: When executing the ``make uninstall`` command, verify the ``venv`` is activated. Not doing so may lead to removing third-party modules installed via ``pip`` at the user level. ``restore`` Deletes any directory that was generated by automated tests, formatting, linting or building the package. This can be helpful in circumstances when a clean install is required. ``clean`` Removes all generated documentation files from the ``docs/_build`` directory. ``test`` Runs the unit tests using the ``pytest`` library. ``lint`` Checks the code in both the ``src`` and ``tests`` directories for formatting and style issues. ``format`` Automatically formats the code in both ``src`` and ``tests`` directories. .. tip:: It is not required to run the ``make format`` command as the GitHub runner will do this automatically. However, it is encouraged to run the ``make lint`` command before submitting your PR. Next Steps ---------- If you have any questions about the process of Contributing, you are welcome to reach out. We are both fairly active on the `MacAdmins Slack `_. Additionally, if you are not familiar with the process of pull requests, `GitHub provides documentation `_ on the topic. For visual learners, the YouTube channel `Keep on Coding `_ provides an excellent demonstration video.