Skip to content

Contributing to Liferay AI Commerce Accelerator

Thank you for your interest in contributing to the Liferay AI Commerce Accelerator! Contributions from the team and community are what make this project successful.

By contributing to this repository, you agree to abide by our Code of Conduct.

🚀 Getting Started

1. Prerequisites

Ensure you have the following installed on your local machine:

  • Node.js (v22.x or later, managed via .nvmrc)
  • Yarn (v1.22.x)
  • Java (v17 or v21, required for Liferay Workspace/Gradle)
  • Docker (Required for the LLD/LDM local server stacks)
  • Liferay Docker Manager (LDM) (npm install -g @google/gemini-cli or similar developer setup)

2. Fork & Clone

  1. Fork the repository on GitHub.
  2. Clone your fork locally:
git clone https://github.com/YOUR-USERNAME/liferay-ai-commerce-accelerator.git
cd liferay-ai-commerce-accelerator
  1. Set up the upstream remote:
git remote add upstream https://github.com/peterrichards-lr/liferay-ai-commerce-accelerator.git

🛠️ Development Workflow

We use a monorepo structure managed by Gradle (Liferay Workspace) with Node/Yarn workspaces under client-extensions/.

📦 Project Structure

  • /client-extensions/ai-commerce-accelerator-frontend/ — React SPA Dashboard
  • /client-extensions/ai-commerce-accelerator-microservice/ — Node/Express Backend API
  • /client-extensions/ai-commerce-accelerator-configuration/ — OSGi Caddy configuration element
  • /client-extensions/liferay-accelerator-sdk/ — Shared SDK for Liferay APIs & contracts

🔨 Compilation and Building

To install all dependencies and build all client extensions in one command, run from the root:

./gradlew deploy

This deploys compiled client extension .zip archives into /bundles/osgi/client-extensions/ ready for Liferay.

🧪 Running Unit Tests

All packages have dedicated Vitest suites. You can run the entire unit test suite across all subprojects:

./gradlew test

Or run them directly inside a specific folder (e.g. client-extensions/liferay-accelerator-sdk):

yarn test

🛡️ End-to-End (E2E) Testing

We use Liferay Docker Manager (LDM) and Playwright to run comprehensive E2E tests against a real DXP container. To run the full E2E suite locally:

LIFERAY_API_PASSWORD=test LIFERAY_API_USERNAME=test@liferay.com bash scripts/run-e2e-ldm.sh -v -k

📐 Styling & Standards

To ensure consistency, we enforce strict linting, formatting, and commit rules.

Code Formatting

We use Prettier and ESLint. Code is automatically formatted and validated during git commits via Husky and lint-staged. You can format your changes manually:

yarn lint

Commit Messages

We enforce Conventional Commits. Commit messages must follow this structure:

<type>(<scope>): <description>

[optional body]

Allowed types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Formatting, missing semi-colons, etc. (no production code change)
  • refactor: Refactoring production code (neither fixes a bug nor adds a feature)
  • test: Adding missing tests or correcting existing tests
  • chore: Updating grunt tasks, build configurations, etc. (no production code change)

Shared docs files

Six files in this repository are copies, not originals. Their canonical versions live on the main branch of ai-agent-template, which seeds them into every project built with --docs-site, so the three Liferay tools sites render the same way:

Here Upstream
overrides/main.html same path
overrides/partials/copyright.html same path
scripts/mkdocs_github_alerts.py same path
scripts/check_docs_rendered.py same path
scripts/check_template_drift.py same path
docs/assets/stylesheets/liferay-blue.css .agents/templates/docs-profiles/liferay/liferay-blue.css

Never edit a copy. Change the canonical file in the template, through a pull request there, then copy it back unchanged. scripts/check_template_drift.py --docs-site --fail-on-drift runs on every pull request and fails on any difference, so a local edit cannot survive review.

Everything this site needs to say for itself goes in mkdocs.yml instead — under extra.docs_standard for the shared checks, or in a second stylesheet listed after liferay-blue.css in extra_css. The rule, and what the standard requires of a page, are in the template's CONTRIBUTING.md ("Shared docs files") and .agents/skills/docs-site-standard/SKILL.md.

See #1335.

📥 Submitting a Pull Request

  1. Create a Branch: Always branch from master and name it logically matching the Conductor Track IDs:
git checkout -b feature/persona-orders
  1. Commit Changes: Ensure your commit messages are conventional and all linting/testing passes.
  2. Sync with Upstream: Keep your branch up to date:
git fetch upstream
git rebase upstream/master
  1. Push & PR: Push to your fork and submit a PR to the upstream repository. Ensure you describe what changed and why (include test logs or manual steps to verify).

📋 Issue-Driven & Peer-Review Flow (Strict Requirements)

This repository enforces a strict process for all contributors (humans and agents alike):

  • GitHub Issues for Recording: All tasks (bugs, enhancements, feature requests, documentation, tooling) MUST be recorded in a GitHub issue before any code changes are made.
  • Impact Analysis & Plan: For every issue, the contributor must analyze the issue details against the codebase and write out a detailed implementation plan.
  • PR-Issue Linkage: All Pull Requests must link back to their originating GitHub issue using conventional keywords in the description (e.g. Closes #123, Resolves #123, or Follows up on #123).
  • Peer Review: A review from another contributor (human developer or peer AI agent) is encouraged before merging whenever a second contributor is available. This repository is not currently branch-protection-enforced for review count (required_approving_review_count: 0), since it's presently solo-maintained — merging still requires a PR with a passing CI/build-and-test check, just not a second approver.

🛡️ Repository Branching & PR Rulesets (Strict Gates)

To maintain absolute code quality, stability, and a logical git history as the accelerator expands, this repository enforces the following strict engineering gates:

1. Feature Branch Isolation

  • Direct pushes to the remote master branch are strictly prohibited for new roadmap items.
  • All new developments, refactoring, or track features MUST be developed on isolated branches named feature/<track-id> (matching active items in the Conductor Tracks Registry, e.g., feature/persona-orders).

2. Local Pre-flight Gatekeeper (verify:all)

  • Before pushing any branch or opening/updating a Pull Request, developers (and AI assistants) MUST ensure the required CI/build-and-test check passes: Prettier, ESLint, markdownlint, a Gradle build, and the full unit test suite (yarn test). This runs automatically on every PR via .github/workflows/ci.yml; run it locally first (yarn prettier --check . && yarn workspaces run eslint . && yarn lint:md && ./gradlew build -x test && yarn test) to catch failures before pushing.
  • The full Playwright E2E suite is not a per-PR gate — against a real Liferay DXP container it takes on the order of 1.5 hours, which is untenable to run on every PR. It instead runs nightly via .github/workflows/e2e-verification.yml (schedule-only, and skips itself automatically if nothing has landed on master since the last successful run), plus on-demand via workflow_dispatch or release: published.
  • Still, run it yourself before opening a PR that touches generator/workflow logic, LDM integration, or anything else the Playwright suite exercises — a regression there won't be caught until the next nightly run otherwise:
LIFERAY_API_PASSWORD=test LIFERAY_API_USERNAME=test@liferay.com bash scripts/run-e2e-ldm.sh -v -k

3. Squash and Merge Policy

  • All Pull Requests merged into master MUST be squashed into exactly one linear commit.
  • This keeps our master git log clean, logical, and highly parseable.

4. Squash Message Conventional Spec

  • The final squashed commit message upon PR merge must follow conventional spec mapping to the track or component scope:
feat(<track-id>): brief summary of what was added

- Detail 1 of change
- Detail 2 of change

(e.g., feat(persona-orders): implement intelligent AI persona order seeding)

Thank you for contributing!

Last Updated: 2026-10-16 | Last Reviewed: 2026-10-16

Last Reviewed: 2026-10-15