Add pre-commit configuration and update contributing guidelines

.github/workflows/codeql.yml

@@ -96,4 +96,4 @@ jobs:
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@v4
       with:
-        category: "/language:${{matrix.language}}"
+        category: "/language:${{matrix.language}}"

.github/workflows/publish.yml

@@ -43,7 +43,7 @@ jobs:
     environment:
       name: release
       url: https://pypi.org/project/matrix-python/${{ github.event.release.tag_name }}
-    
+
     steps:
       - name: Retrieve release distributions
         uses: actions/download-artifact@v4
@@ -52,4 +52,4 @@ jobs:
           path: dist/
 
       - name: Publish release distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/scorecard.yml

@@ -49,4 +49,4 @@ jobs:
       - name: "Upload to code-scanning"
         uses: github/codeql-action/upload-sarif@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.29.5
         with:
-          sarif_file: results.sarif
+          sarif_file: results.sarif

.gitignore

@@ -177,4 +177,4 @@ cython_debug/
 
 .vscode
 matrix/_version.py
-site/
+site/

.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+default_language_version:
+  python: python3
+
+default_stages: [pre-commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        stages: [pre-commit]
+      - id: check-toml
+        stages: [pre-commit]
+      - id: check-yaml
+        exclude: ^docs/mkdocs\.yml$
+        stages: [pre-commit]
+      - id: end-of-file-fixer
+        stages: [pre-commit]
+      - id: trailing-whitespace
+        stages: [pre-commit]
+
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: python -m black
+        language: system
+        stages: [pre-commit]
+        types_or: [python, pyi]
+
+      - id: mypy
+        name: mypy
+        entry: python -m mypy matrix
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+        types_or: [python, pyi]
+
+      - id: pytest
+        name: pytest
+        entry: python -m pytest
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 Thank you for your interest in contributing to the matrix.py! As an open source project, many kinds of contributions are welcome.
 
 ## How can you contribute?
-You can contribute to this project in the follwing ways
+You can contribute to this project in the following ways
 
 - Report Bugs
 - Add new features
@@ -12,18 +12,36 @@ You can contribute to this project in the follwing ways
 **Warning:** Non-trivial pull requests must have an [issue](https://github.com/Code-Society-Lab/matrixpy/issues) proposing the changes.
 
 ## Setup
-1. Clone the Textual repository
-2. Create a virtual enviroment
-3. Install the dependencies
+1. Clone the matrix.py repository
+2. Create and activate a virtual environment
+3. Install the development dependencies and enable the Git hooks.
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+```
+
+
+After installation, the Git hooks run automatically before each commit to check formatting, typing, and tests.
+The hooks include running:
+- black
+- mypy
+- pytest
+
+Run the full hook suite manually with:
+
+```bash
+pre-commit run --all-files
+```
 
 ## Guidelines
 Read any issue instructions carefully. Feel free to ask for clarification if any details are missing.
 
 Add docstrings to all of your code (functions, methods, classes, ...). The codebase should have enough examples for you to copy from.
 
 Write tests for your code.
-    If you are fixing a bug, make sure to add regression tests that link to the original issue.
-    If you are implementing new features, make sure to add tests
+- If you are fixing a bug, add a regression test that references the original issue.
+- If you are implementing a new feature, add tests covering the new functionality.
 
 ## Before opening a PR
 

docs/docs/guides/commands.md

@@ -42,7 +42,7 @@ Make your command clearer by adding a description:
 async def ping(ctx):
     await ctx.reply("Pong 🏓")
 ```
-This description shows up in the help command when users type !help ping. 
+This description shows up in the help command when users type !help ping.
 
 ### Customizing the Command Name
 Sometimes you want the command name to be different from the function name:
@@ -67,14 +67,14 @@ As you saw, every command must have a ctx (context) parameter. The [`Context`](.
 async def whoami(ctx):
     # Who sent the command?
     sender = ctx.sender  # "@alice:example.com"
-    
+
     # What room are we in?
     room_name = ctx.room_name  # "General Chat"
     room_id = ctx.room_id  # "!abc123:example.com"
-    
+
     # What was the message?
     message = ctx.body  # "!whoami"
-    
+
     # Send all this info back
     await ctx.reply(f"You are {sender} in {room_name} ({room_id}) and your message was {message}")
 ```

docs/docs/guides/error-handling.md

@@ -1,5 +1,5 @@
 # Handling Errors
-Errors happen! A user might provide invalid input, your API might fail, or someone might misuse a command. Let's make your bot handle these gracefully through error handlers. 
+Errors happen! A user might provide invalid input, your API might fail, or someone might misuse a command. Let's make your bot handle these gracefully through error handlers.
 
 Error handlers can handle any type of exception, built-in by Python, from matrix.py or any other libraries. See the [`errors`](../reference/errors.md) reference for the full list of built-in error types.
 

docs/docs/guides/index.md

@@ -69,7 +69,7 @@ bot.start(config=Config(
 ```
 - Now your bot will:
 - Log all messages
-- Reply to `!ping` with `Pong!` 
+- Reply to `!ping` with `Pong!`
 - Echo messages with `!say <text>`
 
 # Resources

docs/docs/guides/introduction.md

@@ -32,7 +32,7 @@ Before installing Matrix.py, it's strongly recommended to create a virtual envir
     ```bash
     source venv/bin/activate
     ```
-    
+
     On Windows (PowerShell):
     ```bash
     venv\Scripts\Activate
@@ -87,7 +87,7 @@ Matrix.py allows you to listen to these events using the `@bot.event` decorator.
 For example, to react whenever a message is sent:
 ```python
 from matrix import Bot, Context
-from matrix.bot import MatrixRoom, RoomMessageText 
+from matrix.bot import MatrixRoom, RoomMessageText
 
 bot = Bot()
 

docs/mkdocs.yml

@@ -120,4 +120,4 @@ nav:
       - Cooldowns: examples/cooldown.md
       - Error Handling: examples/error-handling.md
       - Extension: examples/extension.md
-      - Scheduler: examples/scheduler.md
+      - Scheduler: examples/scheduler.md

pyproject.toml

@@ -31,6 +31,7 @@ dev = [
     "pytest-asyncio==1.4.0",
     "black==26.5.1",
     "mypy==2.1.0",
+    "pre-commit==4.6.0",
     "types-PyYAML==6.0.12.20260518",
     "types-Markdown==3.10.2.20260518",
 ]
@@ -59,4 +60,4 @@ write_to = "matrix/_version.py"
 omit = [
     "matrix/_version.py",
     "matrix/__init__.py",
-]
+]