This guide is intended for developers contributing to Altly for WordPress. It covers repository structure, getting started with local development, and our overall development workflow.

Repository Structure

• Main Plugin File:

  The root of the repository contains the primary PHP file (altly.php) that defines the plugin header and initializes plugin functionality. Currently, the plugin is an MVP and all PHP code is contained in this single file. As part of our roadmap, we plan to refactor the code for improved organization, readability, and management.

• build/ Folder:

  Generated by Webpack, this folder contains the compiled JavaScript and CSS assets for the plugin’s front-end.

• src/ Folder:

  Contains the source code for your front-end assets, organized into component folders. Each component is included in a parent shell that wraps the app. While the current organization is easy to read and maintain, we plan to review and expand this structure as we build out a library of reusable components for use across all integrations, plugins, and platforms.

• readme.txt:

  Documentation for end users is maintained here.

Getting Started

1. Clone the Repository:

   git clone <https://github.com/prolific-digital/altly-wp.git>
   cd altly-wp
   

2. Install Dependencies:

   Use either npm or yarn:

   npm install
   # or
   yarn
   

3. Environment Setup:

   Create a .env.local file in the project root to configure the external API endpoints that the plugin uses to connect to Altly. These environment variables are critical for proper integration:

   REACT_APP_API_VALIDATE_URL=http://localhost:3000/v2/validate
   REACT_APP_API_QUEUE_URL=http://localhost:3000/v2/queue
   

   If you are not running the API locally, update these values to:

   REACT_APP_API_VALIDATE_URL=https://api.altly.io/v2/validate
   REACT_APP_API_QUEUE_URL=https://api.altly.io/v2/queue
   

4. Start the Development Server:

   Run:

   npm run dev
   # or
   yarn dev
   

   This command compiles your files on the fly while watching for changes, so you can preview your updates in real time. Note: HMR (Hot Module Replacement) is not used because WordPress requires these assets to be hosted and accessed as static files.

   Open your browser and visit your local WordPress site, for example:

   http://your-local-wordpress-site/wp-admin/upload.php?page=altly

Development Workflow

Compiling and Testing

• Live Compilation: When running yarn dev (or npm run dev), your source files in the src/ folder are automatically compiled into the build/ folder. The development server watches for file changes, allowing you to preview updates immediately. Remember, HMR is not enabled because WordPress serves the assets as static files.

Versioning

• Version Updates: Before releasing a new version, update the version number in both altly.php and readme.txt following Semantic Versioning (MAJOR.MINOR.PATCH).

Branching and Commit Strategy