feat(repo): add Changesets with Trusted Publishing for automated releases

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/CI.md

@@ -1,7 +1,7 @@
-# Continuous Integration
+# Continuous Integration & Release
 
 ## Overview
-This project uses GitHub Actions for continuous integration. The CI workflow runs automatically on all pull requests and pushes to the `main` branch.
+This project uses GitHub Actions for continuous integration and automated releases. Workflows run automatically on all pull requests and pushes to the `main` branch.
 
 ## CI Workflow
 The CI workflow (`.github/workflows/ci.yml`) runs the following checks in sequence:
@@ -58,6 +58,64 @@ The `main` branch is protected and requires:
 - Pull request reviews (if configured)
 - Branches to be up to date before merging
 
+## Release Process
+
+This project uses [Changesets](https://github.com/changesets/changesets) for automated versioning and publishing to npm.
+
+### How It Works
+
+1. **Create changes** - Make your code changes as usual
+2. **Add changeset** - Run `yarn changeset` to document the change
+3. **Open PR** - Create a pull request with your changes + changeset
+4. **PR merged** - After review, your PR is merged to main
+5. **Version PR created** - The release workflow automatically creates a "Version Packages" PR
+6. **Publish** - When the Version PR is merged, packages are published to npm
+
+### For Contributors
+
+When making user-facing changes, always create a changeset:
+
+```bash
+yarn changeset
+```
+
+Select the affected packages, choose the bump type (patch/minor/major), and describe your changes. This will be included in the changelog.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed instructions.
+
+### For Maintainers
+
+#### Normal Releases
+1. Review and merge PRs with changesets
+2. Review the auto-generated "Version Packages" PR
+3. Merge the Version PR to trigger publishing
+
+#### Dry Run Testing
+To test the release process without publishing:
+
+```bash
+# Trigger the release workflow manually
+# Go to Actions → Release → Run workflow
+# Select "dry_run: true"
+```
+
+#### NPM Trusted Publishing Setup
+This project uses NPM's Trusted Publishing (OIDC) for secure, token-free publishing:
+
+**One-time setup on NPM:**
+1. Go to each package's settings on npmjs.com
+2. Configure Trusted Publisher:
+   - Publisher: GitHub Actions
+   - Repository: `lytics/lytics-lab`
+   - Workflow: `release.yml`
+   - Environment: `production`
+3. Set publishing access to "Require 2FA and disallow tokens" for maximum security
+
+**GitHub Environment:**
+The `production` environment must exist in repository settings (Settings → Environments).
+
+No NPM tokens required! Authentication happens automatically via OIDC.
+
 ## Adding New Checks
 To add additional CI checks, edit `.github/workflows/ci.yml` and add new steps under the `steps` section.
 

.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Run in dry-run mode (no actual publishing)"
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "true"
+          - "false"
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.20.0"
+          cache: "yarn"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Setup Nx cache
+        uses: actions/cache@v3
+        with:
+          path: .nx/cache
+          key: ${{ runner.os }}-nx-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-nx-
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: yarn release
+          version: yarn version-packages
+          commit: "chore: version packages"
+          title: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+          DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
+
+      - name: Publish Summary
+        if: steps.changesets.outputs.published == 'true'
+        run: |
+          echo "### 📦 Published Packages" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.changesets.outputs.publishedPackages }}" | jq -r '.[] | "- \(.name)@\(.version)"' >> $GITHUB_STEP_SUMMARY

CONTRIBUTING.md

@@ -0,0 +1,225 @@
+# Contributing to Lytics Lab
+
+Thank you for contributing to Lytics Lab! This guide will help you get started.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 22.20.0 (managed via Volta)
+- Yarn 1.22.18
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/lytics/lytics-lab.git
+cd lytics-lab
+
+# Install dependencies
+yarn install
+
+# Run tests
+yarn test
+
+# Run linting
+yarn lint
+
+# Type check
+yarn typecheck
+
+# Build all packages
+yarn build
+```
+
+## Making Changes
+
+### 1. Create a Branch
+
+```bash
+git checkout -b issue/[number]-[description]
+```
+
+### 2. Make Your Changes
+
+- Write clear, concise code
+- Add tests for new features
+- Update documentation as needed
+- Follow the existing code style (enforced by Biome)
+
+### 3. Run Quality Checks
+
+```bash
+# Run all checks locally before pushing
+yarn lint
+yarn typecheck
+yarn test
+yarn build
+```
+
+## Changesets Workflow
+
+We use [Changesets](https://github.com/changesets/changesets) for versioning and publishing. This ensures clear changelogs and semantic versioning.
+
+### Creating a Changeset
+
+When you make changes that should be released, create a changeset:
+
+```bash
+yarn changeset
+```
+
+This will prompt you to:
+
+1. **Select packages** - Which packages did you change?
+2. **Select bump type** - What type of change is this?
+   - **patch** (1.0.0 → 1.0.1) - Bug fixes, minor changes
+   - **minor** (1.0.0 → 1.1.0) - New features, backwards compatible
+   - **major** (1.0.0 → 2.0.0) - Breaking changes
+3. **Write a summary** - Describe your changes (will appear in CHANGELOG)
+
+This creates a markdown file in `.changeset/` that will be committed with your PR.
+
+### Example Workflow
+
+```bash
+# 1. Make your changes
+git checkout -b feat/add-new-feature
+
+# 2. Create a changeset
+yarn changeset
+# Select: experience-editor
+# Choose: minor
+# Summary: "Add support for custom themes"
+
+# 3. Commit everything together
+git add .
+git commit -m "feat(experience-editor): add custom theme support"
+git push origin feat/add-new-feature
+
+# 4. Open a PR
+```
+
+### What Happens Next?
+
+1. **Your PR is reviewed** - Maintainers review your code and changeset
+2. **PR is merged** - Your changeset is merged to main
+3. **Version PR is created** - A bot creates a "Version Packages" PR with:
+   - Updated package versions
+   - Updated CHANGELOGs
+   - All pending changesets combined
+4. **Maintainer merges Version PR** - Packages are automatically published to npm
+
+### Changeset Guidelines
+
+**Do create a changeset when:**
+
+- Adding features
+- Fixing bugs
+- Making breaking changes
+- Updating dependencies that affect users
+
+**Don't create a changeset for:**
+
+- Documentation updates
+- Internal refactors (no API changes)
+- CI/build configuration changes
+- Development dependencies
+
+## Commit Message Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+```
+
+### Types
+
+- `feat` - New feature
+- `bug` - Bug fix
+- `maint` - Maintenance/refactoring
+
+### Scopes
+
+- `experience-editor` - Changes to experience-editor package
+- `recommendation-block` - Changes to recommendation-block package
+- `repo` - Repository-level changes
+- `ci` - CI/CD changes
+- `deps` - Dependency updates
+- `docs` - Documentation
+- `tests` - Test changes
+
+### Examples
+
+```
+feat(experience-editor): add date range display condition
+
+bug(recommendation-block): fix API timeout issue
+
+maint(repo): upgrade to Biome 2.0
+```
+
+## Pull Request Process
+
+1. **Create a clear PR title** - Following conventional commit format
+2. **Include changeset** - Add changeset if user-facing changes
+3. **Fill out PR template** - Provide context and testing notes
+4. **Wait for CI** - All checks must pass
+5. **Address feedback** - Respond to review comments
+6. **Squash and merge** - Maintainers will merge when ready
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+yarn test
+
+# Run tests in watch mode
+yarn test:watch
+
+# Run tests with coverage
+yarn cover
+
+# Run tests for specific package
+cd packages/experience-editor
+yarn test
+```
+
+### Writing Tests
+
+- Place tests in `__tests__` folders
+- Use descriptive test names
+- Follow existing patterns
+- Aim for good coverage of new code
+
+## Code Style
+
+We use [Biome](https://biomejs.dev/) for linting and formatting:
+
+```bash
+# Check for issues
+yarn lint
+
+# Auto-fix issues
+yarn lint:fix
+
+# Format code
+yarn format
+```
+
+Your editor should auto-format on save if configured properly.
+
+## Need Help?
+
+- **Questions?** Open an issue with the "question" label
+- **Bug?** Open an issue with the "bug" label
+- **Feature idea?** Open an issue with the "enhancement" label
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's license.