Gravity Forms Giveaway Add-On — Development Guide
=================================================

Version: 0.1.0-alpha.1


REPOSITORY STRUCTURE
--------------------

  giveaway.php                      Plugin bootstrap
  includes/
    class-gf-giveaway-addon.php    GFAddOn — settings, AJAX
    class-gf-giveaway-engine.php   Eligibility pool + random draw
    class-gf-giveaway-history.php  wp_gf_giveaway_draws table
    class-gf-giveaway-page.php     Admin drawing UI
    class-gf-giveaway-form-settings.php
  assets/                          Admin CSS/JS
  bin/
    setup-local-test.php           LocalWP smoke: form + entries + dry draw
    test-draw.php                  Saves a draw to history
  tests/                           PHPUnit + Playwright


REQUIREMENTS (DEV)
------------------

  - PHP 7.4+ (8.x recommended for local testing)
  - Composer
  - Node.js 24.x (see .nvmrc) — for Playwright / wp-env
  - Gravity Forms — for integration tests (not bundled in this repo by default)


LOCAL SETUP (LocalWP)
---------------------

1. Clone this repo into your Local site plugins directory, or symlink:

     ln -s /path/to/gravityformsgiveaway \
       ~/Local\ Sites/yoursite/app/public/wp-content/plugins/gravityformsgiveaway

2. Activate the plugin in WP Admin.

3. Run the CLI smoke bootstrap (creates test form, seeds entries):

     php bin/setup-local-test.php

   If you see "MySQL socket not found", start your Local site first.

   Edit bin/lib/local-env.php if your Local site path differs.

4. Verify a saved draw:

     php bin/test-draw.php


CODE QUALITY
------------

  composer install
  composer phpcs      # WordPress + RocketGenius standards
  composer phpstan
  composer phpunit

  Note: PHPCS uses the private gravityforms/rgcodestandards ruleset.
  You need SSH access to github.com/gravityforms/rgcodestandards.


AUTOMATED TESTS (wp-env + Playwright)
--------------------------------------

  npm install
  npm run test:pw:start
  npm run test:pw:run

  Playwright tests live in tests/playwright/e2e/.
  wp-env config: .wp-env.json


GITHUB ACTIONS
--------------

  .github/workflows/code-quality.yml  — PHPCS, PHPStan, PHPUnit
  .github/workflows/playwright.yml    — E2E settings page smoke test

  CI requires a BOT_DEPLOY_TOKEN secret to fetch Gravity Forms for tests.


BUILD RELEASE ZIP
-----------------

  From the parent GF Addons workspace:

    ./bin/build-release-zip.sh giveaway

  Output: dist/gravityformsgiveaway-0.1.0-alpha.1.zip

  Standalone: zip the plugin folder excluding vendor/, node_modules/,
  tests/, .github/, composer.json, and other dev-only files.


LABS AUTO-UPDATE
----------------

  _enable_rg_autoupgrade is true on GF_Giveaway_AddOn. Updates are delivered
  through the Gravity Forms GFAutoUpgrade mechanism when published to labs.


CODING STANDARDS
----------------

  - Tabs for PHP indentation
  - Text domain: gravityformsgiveaway
  - Extend GFAddOn; bootstrap on gform_loaded priority 5
  - No runtime Composer dependencies
