V1 Ready

Author: mtctx

.idea/misc.xml

@@ -1,107 +1,152 @@
-# Contributing to Squishy
+# Contributing to Zappy
 
-Hey there! 👋
+Hey there!
 
-We’re super excited that you want to contribute to **Squishy**. It’s an open-source, high-performance Minecraft
-implementation, and we couldn’t do it without awesome community members like you. By contributing, you’re agreeing to
-follow our **[Code of Conduct](https://www.google.com/search?q=CODE_OF_CONDUCT.md)**—basically, just be kind,
-respectful, and collaborative.
+We’re **thrilled** you want to contribute to **Zappy** — the fast, type-safe, KSP-powered mock data generator for
+Kotlin.  
+Your help makes it better for everyone. By contributing, you agree to follow our **[Code of Conduct](CODE_OF_CONDUCT.md)
+** — in short: **be kind, be respectful, be awesome**.
 
-## How You Can Help
+---
 
-There are lots of ways to pitch in:
+## How You Can Help
 
-* **Report bugs** – Help us squash those pesky issues.
-* **Submit code** – Add new features, fix bugs, or improve existing functionality.
-* **Improve docs** – Make our documentation clearer and easier for everyone.
-* **Share feedback** – Test new stuff and tell us what works (or doesn’t).
+Even small contributions go a long way:
 
-Even small contributions make a big difference!
+* **Report bugs** – Found a weird mock? Let us know!
+* **Submit code** – Add new ZPL providers, fix bugs, improve performance
+* **Improve docs** – Make the README, examples, or API clearer
+* **Add examples** – Show off cool use cases in `zappy-test`
+* **Suggest features** – Want `<hex-color>`? `<iban>`? Open an issue!
 
 ---
 
 ## Getting Started
 
 ### Set Up Your Development Environment
 
-Here’s how to get your local setup ready:
-
-1. **Install the prerequisites**
-   Make sure you have **JDK 21** or later installed.
+1. **Install prerequisites**
+    - **JDK 17+** (Zappy uses Kotlin 1.9+)
+    - **IntelliJ IDEA** (recommended) or any IDE with Kotlin + Gradle support
 
 2. **Clone the repo**
 
    ```bash
-   git clone https://github.com/mtctx/Squishy.git
-   cd Squishy
+   git clone https://github.com/mtctx/zappy.git
+   cd zappy
    ```
 
-3. **Open the project**
-   Open the `Squishy` folder in your favorite IDE (IntelliJ IDEA or VS Code with Kotlin plugins work great). Gradle
-   should automatically detect the modules for you.
+3. **Open in your IDE**
+    - Open the root `build.gradle.kts`
+    - Let Gradle sync (it will download KSP, KotlinPoet, etc.)
 
-4. **Run the project**
+4. **Build & Test**
 
    ```bash
-   ./gradlew run
+   ./gradlew build
    ```
 
-   This will build everything you need and start the Squishy client.
+   This compiles all modules and runs the KSP processor.
+
+5. **Run the example**
+
+   ```bash
+   ./gradlew :zappy-test:run
+   ```
+
+   You’ll see:
+   ```
+   Test(username=7g1iH7VlMBM2C)
+   ```
 
 ---
 
 ## Reporting a Bug
 
-The more details you give, the faster we can fix it. When opening an issue
-on [GitHub Issues](https://www.google.com/search?q=https://github.com/mtctx/Squishy/issues), try to include:
+Help us fix it fast! When opening an issue on [GitHub Issues](https://github.com/mtctx/zappy/issues):
 
-* A **short, clear title** describing the problem
-* **Steps to reproduce** the issue
-* **What you expected** to happen vs. **what actually happened**
-* Your **Squishy version**
-* Your **OS and system info**
-* Any **logs or screenshots** that help explain the problem
+* **Clear title** – e.g., `mock<User>() generates invalid email with @Name(":")`
+* **Steps to reproduce** – Code snippet + build command
+* **Expected vs Actual** – What should happen? What did?
+* **Zappy version** – `1.0.0`, `main`, or commit SHA
+* **Logs/screenshots** – KSP warnings, stack traces, etc.
 
 ---
 
 ## Submitting Code Changes
 
-We love contributions! Before you start, make sure you’re familiar with our coding standards.
+We **love PRs**! Here’s the flow:
 
 ### Pull Request Process
 
-1. **Fork the repo** on GitHub.
-
-2. **Create a new branch** with a descriptive name, like `feature/cool-new-thing` or `fix/bug-123`:
-
+1. **Fork** the repo on GitHub
+2. **Create a branch**:
+   ```bash
+   git checkout -b feature/hex-color-provider
+   # or
+   git checkout -b fix/email-validation
+   ```
+3. **Make your changes**
+    - Add tests in `zappy-test` if possible
+    - Update docs if adding public APIs
+4. **Commit clearly**:
    ```bash
-   git checkout -b fix/issue-123-bug-name
+   git commit -m "feat: add <hex-color> ZPL provider"
    ```
+5. **Push & open PR** to `main`
+6. **Link issues**: Use `Closes #123` if applicable
 
-3. **Make your changes** in the relevant module(s).
+---
 
-4. **Write clear commit messages**.
+### Code Style
 
-5. **Push your branch**:
+* Follow **Kotlin Coding Conventions**
+* Use **4-space indentation**
+* Format with **IntelliJ’s default Kotlin formatter**
+* Keep functions small and focused
+* Add KDocs for public APIs
 
-   ```bash
-   git push origin your-branch-name
-   ```
+> No linter config needed — just keep it clean and consistent.
 
-6. **Open a Pull Request** from your branch to the `main` branch.
+---
 
-7. **Explain your changes** in the PR description, and if it fixes a bug, reference it (e.g., `Closes #123`).
+## Project Structure (Quick Guide)
 
-### Code Style
+```
+zappy/
+├── zappy-core/          → ZPL engine, annotations, providers
+├── zappy-processor/     → KSP code generation
+├── zappy-test/          → Example usage + integration tests
+└── build.gradle.kts     → Multi-module config
+```
+
+---
 
-We follow standard Kotlin conventions. Make your code clean, readable, and consistent. You can use your IDE’s formatter
-or a linter like **Qodana** (configured in `qodana.yml`).
+## Testing Your Changes
+
+```bash
+# Full build + KSP + tests
+./gradlew build
+
+# Just run the example
+./gradlew :zappy-test:run
+```
+
+The KSP processor will regenerate `MockProviders.kt` on every build.
 
 ---
 
 ## Need Help?
 
-Got questions, stuck on setup, or want to brainstorm an idea? Then just create a *
-*[Discussion](https://github.com/mtctx/Squishy/discussions)**.
+* **Stuck on setup?** → Open an issue
+* **Idea to discuss?** → Start a [Discussion](https://github.com/mtctx/zappy/discussions)
+* **Want to pair?** → Ping `@mtctx` on GitHub
+
+---
+
+## Thank You
+
+Every contribution — from a typo fix to a new provider — makes Zappy better.  
+**You’re making Kotlin testing smoother for everyone.**
 
-Thanks for helping make Squishy even better! We really appreciate it. 💜
+Let’s build something awesome together!