From 478cb50894bf2148d01c1d400adabeea6780178d Mon Sep 17 00:00:00 2001 From: Mirza Kopic Date: Wed, 29 Oct 2025 13:57:08 +0100 Subject: [PATCH 1/4] feat: attempt at versioning --- .DS_Store | Bin 6148 -> 6148 bytes .github/workflows/pages.yaml | 23 +- .gitignore | 3 + .vitepress/config.mts | 9 +- .vitepress/theme/Layout.vue | 15 + .../theme/components/VersionSelector.vue | 125 ++++ .vitepress/theme/index.js | 6 +- README.md | 17 +- how-to-deploy/how-to.md | 558 ++++++++++++++++++ how-to-deploy/verify-deployment.md | 385 ++++++++++++ 10 files changed, 1133 insertions(+), 8 deletions(-) create mode 100644 .vitepress/theme/Layout.vue create mode 100644 .vitepress/theme/components/VersionSelector.vue create mode 100644 how-to-deploy/how-to.md create mode 100644 how-to-deploy/verify-deployment.md diff --git a/.DS_Store b/.DS_Store index 15a6ecb8b0337ad3a6d1f9e9462e61969c9ff807..49c1bf0b970629c84a8cf6de44a6cafc81639c92 100644 GIT binary patch delta 294 zcmZoMXfc=|#>B`mu~2NHo}wr#0|Nsi1A_nqgDyh~Ln=c7Lk>g!#KPtEAPH`U5};5q zkVKMXs7xtN&PmG8&jISgr6ecaFgQ6sw*aVufnnXtLfk5I^Icq$a`KaaDmeI0R_2LE z9(M$?LvYxgo1cPBIS$nY8A#69_F?lx<}#Me3z#=EZf57;=KzKRP~B)qu~2NHo}wrl0|Nsi1A_nqLkUB1Qh9MfQcix-=7)^S8S6n(Yz&DE z#Xy*fEDaRjnN*OISzKaZaE+0PnT3^&ot=}Nn>{u-BfmVjB(bEl*eS6n8pI39&(BGM zu@jTRGE>Xr1w@?l^GXsk^HPhz8ZuK-fl6Y+GxJjN%boH|^HPd|dh3BkL1Z{NIXL45 zB&(~94Gk@I6wD0_YjqT=EsYFx6ih6QYHK+;M3wcegW|Jua`W=Lfvy7rMxdv_fEP-` zs2(5##aB7$hQZ1CxdkusdClbMSKjV+$A~-93ZlV834TMaM=I= diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 4e659a5..9a6a54d 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -4,6 +4,7 @@ on: push: branches: - main + - 'release-*' # Support version branches pull_request: branches: - main @@ -19,8 +20,8 @@ permissions: pull-requests: write # to leave a comment with the preview URL concurrency: - # set separate concurrency groups for main and PR branches - group: ${{ github.event_name == 'pull_request' && format('pages-preview-{0}', github.event.pull_request.number) || 'pages-main' }} + # set separate concurrency groups for each version branch and PR + group: ${{ github.event_name == 'pull_request' && format('pages-preview-{0}', github.event.pull_request.number) || format('pages-{0}', github.ref_name) }} cancel-in-progress: false jobs: @@ -39,9 +40,22 @@ jobs: - id: configure uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 + # Extract version from branch name for versioned deployments + - id: set-version + name: Set documentation version + run: | + if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then + echo "version=main" >> $GITHUB_OUTPUT + elif [[ "${{ github.ref }}" == refs/heads/release-* ]]; then + echo "version=${GITHUB_REF#refs/heads/}" >> $GITHUB_OUTPUT + else + echo "version=" >> $GITHUB_OUTPUT + fi + - run: npm ci - run: npm run build env: + DOCS_VERSION: ${{ steps.set-version.outputs.version }} PAGES_BASE: ${{ github.event_name == 'pull_request' && format('pr-preview/pr-{0}', github.event.pull_request.number) || '' }} # deploy the PR to a preview URL @@ -50,11 +64,12 @@ jobs: with: source-dir: .vitepress/dist - # deploy the build to GitHub Pages + # deploy the build to GitHub Pages (version branches: main, release-*) - uses: JamesIves/github-pages-deploy-action@6c2d9db40f9296374acc17b90404b6e8864128c8 # v4 - if: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main' }} + if: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release-')) }} with: folder: .vitepress/dist branch: gh-pages + target-folder: ${{ steps.set-version.outputs.version }} clean-exclude: pr-preview force: false diff --git a/.gitignore b/.gitignore index 1a7e7d3..4b7990c 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ /.vitepress/cache/ /.vitepress/dist/ public/.DS_Store +.DS_Store +CLAUDE.md +.claude/ \ No newline at end of file diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 6ca406d..246de09 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -8,7 +8,12 @@ export default withMermaid({ ['link', { rel: 'icon', href: '/favicon.ico' }] ], - base: 'PAGES_BASE' in process.env && process.env.PAGES_BASE != '' ? '/' + process.env.PAGES_BASE : '', + // Support versioning: DOCS_VERSION takes precedence, then PAGES_BASE (PR previews), then root + base: 'DOCS_VERSION' in process.env && process.env.DOCS_VERSION != '' + ? '/' + process.env.DOCS_VERSION + '/' + : ('PAGES_BASE' in process.env && process.env.PAGES_BASE != '' + ? '/' + process.env.PAGES_BASE + '/' + : '/'), description: "Platform Mesh - Building upon the Kubernetes API & Resource Model", @@ -68,7 +73,7 @@ export default withMermaid({ ], '/scenarios': { - test: 'Scenarios', + text: 'Scenarios', items: [ { text: 'Scenarios', link: '/scenarios' }, { text: 'Provider to Consumer (P2C)', link: '/scenarios/details.html#provider-to-consumer-p2c' }, diff --git a/.vitepress/theme/Layout.vue b/.vitepress/theme/Layout.vue new file mode 100644 index 0000000..a471b1b --- /dev/null +++ b/.vitepress/theme/Layout.vue @@ -0,0 +1,15 @@ + + + diff --git a/.vitepress/theme/components/VersionSelector.vue b/.vitepress/theme/components/VersionSelector.vue new file mode 100644 index 0000000..fc826ce --- /dev/null +++ b/.vitepress/theme/components/VersionSelector.vue @@ -0,0 +1,125 @@ + + + + + diff --git a/.vitepress/theme/index.js b/.vitepress/theme/index.js index 508d8b4..9686d29 100644 --- a/.vitepress/theme/index.js +++ b/.vitepress/theme/index.js @@ -1,4 +1,8 @@ import DefaultTheme from 'vitepress/theme' +import Layout from './Layout.vue' import './custom.css' -export default DefaultTheme \ No newline at end of file +export default { + ...DefaultTheme, + Layout, +} \ No newline at end of file diff --git a/README.md b/README.md index a80f30f..524c8a2 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,26 @@ suggestions, improvements, or bug fixes, please follow these steps: 1. Fork the repository 2. Create a new branch for your changes 3. Make your changes and commit them with a clear message -4. Test your changes with the local dev server: `npm run dev` +4. Test your changes locally: + ```bash + npm install + npm run dev # Development server at http://localhost:5173 + + # Or test with versioning: + DOCS_VERSION=main npm run build + npm run preview # Preview at http://localhost:4173/main/ + ``` 5. Push your changes to your fork 6. Create a pull request against the `main` branch of this repository +## Deployment (local and github) + +For detailed documentation on versioning, local testing, and GitHub Pages deployment, see the [how-to-deploy](how-to-deploy/) folder: +- [Deployment How-To Guide](how-to-deploy/how-to.md) - Complete guide for local testing, version switching, and deploying to GitHub Pages +- [Verifying Deployment](how-to-deploy/verify-deployment.md) - Step-by-step verification checklist and troubleshooting + + ## Diagrams Diagrams are done excalidraw and can be found here (read-only link): diff --git a/how-to-deploy/how-to.md b/how-to-deploy/how-to.md new file mode 100644 index 0000000..da4ae03 --- /dev/null +++ b/how-to-deploy/how-to.md @@ -0,0 +1,558 @@ +# Documentation Versioning - How-To Guide + +This guide explains how to use the versioning system for Platform Mesh documentation, including local testing and GitHub deployment. + +## Overview + +The documentation uses a **branch-based versioning system**: +- `main` branch → Deployed to `/main/` (latest development docs) +- `release-*` branches → Deployed to `/release-X.Y/` (stable release docs) +- PR previews → Deployed to `/pr-preview/pr-{number}/` (unchanged) + +Each version is independently deployable and maintains its own content while sharing the same VitePress theme and configuration. + +## Local Testing + +### Quick Test (Single Version) + +Test one version at a time to verify builds work correctly: + +```bash +# Test main version +DOCS_VERSION=main npm run build +npm run preview +# Open: http://localhost:4173/main/ +``` + +```bash +# Test release version +DOCS_VERSION=release-0.1 npm run build +npm run preview +# Open: http://localhost:4173/release-0.1/ +``` + +**What to check:** +- ✅ Page loads without errors +- ✅ All styling looks correct +- ✅ Version selector dropdown appears in navigation +- ✅ Navigation links work properly +- ✅ Images and assets load + +**Limitation:** Version switching won't work because only one version exists in the build output at a time. + +### Full Test (Version Switching) + +Test the complete version switching functionality: + +```bash +# 1. Build main version +DOCS_VERSION=main npm run build +mkdir -p test-deploy/main +cp -r .vitepress/dist/* test-deploy/main/ + +# 2. Build release-0.1 version +DOCS_VERSION=release-0.1 npm run build +mkdir -p test-deploy/release-0.1 +cp -r .vitepress/dist/* test-deploy/release-0.1/ + +# 3. Serve both versions +cd test-deploy +python3 -m http.server 8080 +``` + +**Open in browser:** +- `http://localhost:8080/main/` - Main version +- `http://localhost:8080/release-0.1/` - Release version + +**What to check:** +- ✅ Both URLs load correctly +- ✅ Version selector shows all versions +- ✅ Switching versions works (dropdown navigates to different version) +- ✅ Current version is highlighted in dropdown +- ✅ Switching preserves current page path (e.g., `/main/overview/` → `/release-0.1/overview/`) + +**Cleanup after testing:** +```bash +cd .. +rm -rf test-deploy/ +``` + +### Development Server + +For actively developing documentation content: + +```bash +npm run dev +# Open: http://localhost:5173/ +``` + +**Note:** The dev server doesn't use versioned paths. Use this for: +- Writing and previewing content +- Testing theme changes +- Rapid iteration on markdown files + +For version-specific testing, always use the build + preview method. + +## GitHub Deployment + +### Initial Setup (One-Time) + +The versioning system is already configured. The GitHub Actions workflow (`.github/workflows/pages.yaml`) handles: +- Building documentation for version branches +- Deploying to GitHub Pages +- Managing PR previews + +**Prerequisites:** +- GitHub Pages must be enabled (Settings → Pages) +- Deploy from `gh-pages` branch +- Workflow has `contents: write` permission + +### Deploying Main Branch + +Pushing to `main` automatically deploys the latest docs: + +```bash +# Make changes to documentation +git checkout main +# ... edit markdown files ... +git add . +git commit -m "Update documentation" +git push origin main +``` + +**What happens:** +1. GitHub Actions workflow triggers +2. Builds with `DOCS_VERSION=main` +3. Deploys to `gh-pages` branch under `/main/` directory +4. Available at: `https://platform-mesh.github.io/main/` + +**Monitor deployment:** +- Go to repository → **Actions** tab +- Click on the running workflow +- Wait for ✅ completion (typically 1-2 minutes) +- Check deployment at your GitHub Pages URL + +### Creating a Release Branch + +When you're ready to create a stable release version: + +```bash +# 1. Start from latest main +git checkout main +git pull origin main + +# 2. Create release branch (use pattern: release-X.Y) +git checkout -b release-0.1 + +# 3. Push to GitHub +git push -u origin release-0.1 +``` + +**What happens:** +1. GitHub Actions workflow automatically triggers (matches `release-*` pattern) +2. Extracts version from branch name: `release-0.1` +3. Builds with `DOCS_VERSION=release-0.1` +4. Deploys to `gh-pages` branch under `/release-0.1/` directory +5. Available at: `https://platform-mesh.github.io/release-0.1/` + +**Verify deployment:** +1. Check **Actions** tab for workflow run +2. Wait for completion +3. Visit `https://platform-mesh.github.io/release-0.1/` +4. Verify content is correct + +### Updating the Version Selector + +After creating a new release branch, add it to the dropdown: + +```bash +# 1. Edit the version selector component +git checkout main +``` + +Edit `.vitepress/theme/components/VersionSelector.vue`: + +```typescript +const versions: Version[] = [ + { name: 'main', label: 'main (latest)' }, + { name: 'release-0.2', label: 'v0.2' }, // Add new versions here + { name: 'release-0.1', label: 'v0.1' }, +] +``` + +```bash +# 2. Commit and push +git add .vitepress/theme/components/VersionSelector.vue +git commit -m "Add release-0.2 to version selector" +git push origin main +``` + +**Apply to other branches (optional):** +```bash +# Update the dropdown on release branches too +git checkout release-0.1 +git cherry-pick +git push origin release-0.1 +``` + +### Updating Release Documentation + +To fix or update a specific release version: + +```bash +# 1. Checkout the release branch +git checkout release-0.1 + +# 2. Make changes +# ... edit markdown files ... + +# 3. Commit and push +git add . +git commit -m "Fix typo in release-0.1 docs" +git push origin release-0.1 +``` + +**What happens:** +- Workflow triggers automatically +- Rebuilds only the `release-0.1` version +- Redeploys to `/release-0.1/` (overwrites previous deployment) +- Other versions (main, release-0.2, etc.) are unaffected + +## Pull Request Previews + +PR previews continue to work as before, completely independent of versioning. + +### How It Works + +When you open a PR to `main`: + +```bash +# 1. Create a feature branch +git checkout -b feature/my-changes +# ... make changes ... +git add . +git commit -m "Add new feature documentation" +git push origin feature/my-changes + +# 2. Open PR on GitHub +# Go to repository → Pull Requests → New Pull Request +``` + +**What happens:** +1. Workflow triggers on PR events (opened, synchronized) +2. Builds with `PAGES_BASE=pr-preview/pr-{number}` (NOT `DOCS_VERSION`) +3. Deploys to `/pr-preview/pr-{number}/` on `gh-pages` branch +4. Bot comments on PR with preview URL + +**Preview URL:** +`https://platform-mesh.github.io/pr-preview/pr-{number}/` + +**Verify PR preview:** +1. Open the PR on GitHub +2. Wait for workflow to complete +3. Click the preview URL in the bot comment +4. Review your changes before merging + +### PR Preview vs Versioning + +**Key differences:** + +| Feature | PR Preview | Version Branches | +|---------|------------|------------------| +| Trigger | Pull request events | Push to main/release-* | +| Environment Variable | `PAGES_BASE` | `DOCS_VERSION` | +| Base Path | `/pr-preview/pr-{number}/` | `/main/` or `/release-X.Y/` | +| Persistence | Deleted when PR closes | Permanent until branch deleted | +| Purpose | Review changes | Stable documentation | + +**They coexist without conflict:** +- PR previews use `PAGES_BASE` environment variable +- Version branches use `DOCS_VERSION` environment variable +- VitePress config checks `DOCS_VERSION` first, then `PAGES_BASE` +- Different concurrency groups prevent deployment conflicts + +### Testing PR Previews + +To verify PR preview functionality still works: + +```bash +# 1. Create a test branch +git checkout -b test-pr-preview +echo "# Test PR Preview" >> test-file.md +git add test-file.md +git commit -m "Test PR preview deployment" +git push origin test-pr-preview + +# 2. Open PR on GitHub + +# 3. Wait for workflow and check preview URL + +# 4. Verify preview works, then close PR +``` + +## Troubleshooting + +### Build Fails Locally + +**Problem:** `npm run build` fails with errors + +**Solutions:** +1. Clear VitePress cache: + ```bash + rm -rf .vitepress/cache .vitepress/dist + npm run build + ``` + +2. Reinstall dependencies: + ```bash + rm -rf node_modules package-lock.json + npm install + npm run build + ``` + +3. Check for syntax errors in Vue components or config files + +### Version Selector Not Showing + +**Problem:** Dropdown doesn't appear in navigation + +**Check:** +1. Verify `Layout.vue` is being used: + ```bash + cat .vitepress/theme/index.js + # Should show: ...DefaultTheme, Layout, + ``` + +2. Check browser console for JavaScript errors + +3. Rebuild: + ```bash + DOCS_VERSION=main npm run build + npm run preview + ``` + +### Version Switching Shows 404 + +**Problem:** Clicking version in dropdown shows "Page Not Found" + +**Local testing:** +- You need BOTH versions deployed to `test-deploy/` directory +- Follow "Full Test (Version Switching)" steps exactly + +**On GitHub:** +- Verify both branches have been deployed +- Check Actions tab for successful deployments +- Verify URLs work independently: + - `https://platform-mesh.github.io/main/` + - `https://platform-mesh.github.io/release-0.1/` + +### Workflow Not Triggering + +**Problem:** Push to branch doesn't trigger workflow + +**Check:** +1. Branch name matches pattern: + - ✅ `main` - triggers + - ✅ `release-0.1` - triggers (matches `release-*`) + - ✅ `release-1.0` - triggers + - ❌ `rel-0.1` - doesn't match pattern + - ❌ `v0.1` - doesn't match pattern + +2. Workflow file is on the branch: + ```bash + git checkout + ls .github/workflows/pages.yaml + ``` + +3. Check Actions tab for errors or disabled workflows + +### PR Preview Not Deploying + +**Problem:** PR preview workflow runs but doesn't deploy + +**Check:** +1. PR is from same repository (not a fork): + - Workflow has `!github.event.pull_request.head.repo.fork` check + - Fork PRs won't deploy for security reasons + +2. Check workflow run logs in Actions tab + +3. Verify `pr-preview` directory not in `.gitignore` + +### Assets Not Loading (404s) + +**Problem:** Images or CSS not loading, showing 404 errors + +**Cause:** Base path mismatch + +**Check:** +1. Build was done with correct `DOCS_VERSION`: + ```bash + DOCS_VERSION=main npm run build + ``` + +2. Serving from correct path: + - `http://localhost:4173/main/` (not `http://localhost:4173/`) + +3. Markdown image paths are relative or use proper base path + +### Styles Broken After Update + +**Problem:** Site loads but styling is completely wrong + +**Check:** +1. Theme export structure in `.vitepress/theme/index.js`: + ```javascript + export default { + ...DefaultTheme, // Must spread DefaultTheme + Layout, + } + ``` + +2. Custom CSS is imported: + ```javascript + import './custom.css' + ``` + +3. Clear cache and rebuild: + ```bash + rm -rf .vitepress/cache + npm run build + ``` + +## Workflow Reference + +### GitHub Actions Environment Variables + +The workflow automatically sets these based on context: + +| Branch | `DOCS_VERSION` | `PAGES_BASE` | Deploy Path | +|--------|----------------|--------------|-------------| +| `main` | `main` | (empty) | `/main/` | +| `release-0.1` | `release-0.1` | (empty) | `/release-0.1/` | +| PR to main | (empty) | `pr-preview/pr-{number}` | `/pr-preview/pr-{number}/` | + +### Concurrency Groups + +Deployments use separate concurrency groups to prevent conflicts: + +- Main: `pages-main` +- Release branches: `pages-release-0.1`, `pages-release-0.2`, etc. +- PR previews: `pages-preview-123`, `pages-preview-456`, etc. + +This allows: +- Multiple versions to deploy simultaneously +- PR previews to deploy while version deploys are running +- No race conditions or overwriting + +### Manual Workflow Trigger + +You can manually trigger deployment from Actions tab: + +1. Go to repository → **Actions** +2. Select "pages" workflow +3. Click **Run workflow** +4. Select branch to deploy +5. Click **Run workflow** button + +Useful for: +- Redeploying after GitHub Pages issues +- Testing workflow changes +- Forcing a rebuild without code changes + +## Best Practices + +### Version Naming + +Use consistent naming for release branches: +- ✅ `release-0.1`, `release-0.2`, `release-1.0` +- ✅ `release-2024.1`, `release-2024.2` +- ❌ `v0.1`, `0.1`, `rel-0.1` (won't trigger workflow) + +### When to Create Release Branches + +Create a release branch when: +- Major feature is complete and stable +- Ready to freeze documentation for a release +- Need to maintain docs for older versions +- Creating a new product version + +Don't create release branches for: +- Every commit or small change +- Work-in-progress features +- Experimental documentation + +### Maintaining Multiple Versions + +**Update all versions** for: +- Critical bug fixes +- Security updates +- Broken links or errors + +**Update only specific versions** for: +- Version-specific features +- Deprecated functionality (remove from new versions) +- Different behavior between versions + +**Example workflow:** +```bash +# Fix critical typo in all versions +git checkout main +# ... fix typo ... +git commit -m "Fix critical typo" +git push origin main + +# Cherry-pick to release branches +git checkout release-0.1 +git cherry-pick +git push origin release-0.1 + +git checkout release-0.2 +git cherry-pick +git push origin release-0.2 +``` + +### Version Selector Management + +**Keep it updated:** +- Add new versions to dropdown when created +- List versions in reverse chronological order (newest first, except main) +- Use clear labels (`main (latest)`, `v0.2`, `v0.1`) + +**Remove old versions:** +1. Delete the branch: `git push origin --delete release-0.1` +2. Remove from dropdown in `VersionSelector.vue` +3. Optionally: manually delete from `gh-pages` branch + +### Testing Before Merging + +Always test locally before pushing: + +```bash +# 1. Build and test locally +DOCS_VERSION=main npm run build +npm run preview + +# 2. Check for issues +# - Broken links +# - Missing images +# - Formatting problems + +# 3. If good, push to GitHub +git push origin main +``` + +## Summary + +**Local Testing:** +- Quick: `DOCS_VERSION=main npm run build && npm run preview` +- Full: Build both versions to `test-deploy/`, serve with `python3 -m http.server` + +**GitHub Deployment:** +- Main: Push to `main` → deploys to `/main/` +- Release: Push to `release-X.Y` → deploys to `/release-X.Y/` +- PR Preview: Open PR → deploys to `/pr-preview/pr-{number}/` + +**All three coexist independently without conflicts!** + +For questions or issues, check the troubleshooting section or review workflow logs in the Actions tab. diff --git a/how-to-deploy/verify-deployment.md b/how-to-deploy/verify-deployment.md new file mode 100644 index 0000000..664080b --- /dev/null +++ b/how-to-deploy/verify-deployment.md @@ -0,0 +1,385 @@ +# Verifying GitHub Pages Deployment + +After pushing to GitHub, here's how to verify the versioning deployment worked correctly: + +## 1. Check Workflow Execution + +1. Go to your repository on GitHub +2. Click **Actions** tab +3. Find the workflow run for your push +4. Click on it to see details +5. Verify all steps completed successfully (green checkmarks) + +Look for these steps: +- ✅ Checkout code +- ✅ Setup Node.js +- ✅ npm ci +- ✅ npm run build (with DOCS_VERSION set) +- ✅ Deploy to GitHub Pages + +## 2. Inspect the gh-pages Branch + +### Via GitHub Web Interface + +1. Go to your repository +2. Click the branch dropdown (usually shows "main") +3. Select `gh-pages` branch +4. You should see directory structure like: + +``` +gh-pages (branch) +├── main/ +│ ├── index.html +│ ├── assets/ +│ │ ├── app.xxx.js +│ │ ├── chunks/ +│ │ └── ... +│ ├── overview/ +│ ├── scenarios/ +│ └── ... +├── release-0.1/ +│ ├── index.html +│ ├── assets/ +│ └── ... +└── pr-preview/ (if PRs exist) +``` + +### Via Git Locally + +```bash +# Fetch the gh-pages branch +git fetch origin gh-pages + +# Checkout gh-pages branch (don't worry, you can switch back) +git checkout gh-pages + +# List directory structure +ls -la +# Should show: main/, release-0.1/, etc. + +# Check main version files +ls -la main/ +# Should show: index.html, assets/, overview/, scenarios/, etc. + +# Check release version files +ls -la release-0.1/ +# Should show: index.html, assets/, overview/, scenarios/, etc. + +# Switch back to your working branch +git checkout main +``` + +## 3. Test the Deployed URLs + +### Main Version +Visit: `https://platform-mesh.github.io/main/` + +**Check:** +- ✅ Page loads without 404 error +- ✅ Styling is correct +- ✅ Navigation works (Home, Overview, Scenarios) +- ✅ Version selector dropdown shows in nav bar +- ✅ Logo and images load correctly + +**Test navigation:** +- Click "Overview" → Should go to `https://platform-mesh.github.io/main/overview/` +- Click "Scenarios" → Should go to `https://platform-mesh.github.io/main/scenarios` +- Click logo → Should return to `https://platform-mesh.github.io/main/` + +### Release Version +Visit: `https://platform-mesh.github.io/release-0.1/` + +**Check:** +- ✅ Page loads without 404 error +- ✅ All styling and navigation works +- ✅ Version selector shows both "main (latest)" and "v0.1" + +### Version Switching +From `https://platform-mesh.github.io/main/overview/`: +1. Click version dropdown +2. Select "v0.1" +3. Should navigate to `https://platform-mesh.github.io/release-0.1/overview/` +4. Current page path is preserved! + +From `https://platform-mesh.github.io/release-0.1/`: +1. Click version dropdown +2. Select "main (latest)" +3. Should navigate to `https://platform-mesh.github.io/main/` + +## 4. Check PR Previews Still Work + +### Create a Test PR + +```bash +git checkout main +git checkout -b test-pr-preview +echo "# Test" >> test.md +git add test.md +git commit -m "Test PR preview" +git push origin test-pr-preview +``` + +### Open PR and Verify + +1. Go to repository → **Pull Requests** → **New Pull Request** +2. Select `test-pr-preview` branch +3. Create PR +4. Wait for workflow to complete +5. Check for bot comment with preview URL + +**Test preview URL:** +`https://platform-mesh.github.io/pr-preview/pr-{number}/` + +**Verify:** +- ✅ PR preview loads correctly +- ✅ Shows your changes +- ✅ Independent from version deployments +- ✅ Version selector may show (but won't switch correctly in PR preview) + +**Close test PR:** +- Close the PR on GitHub +- Delete the branch: `git branch -D test-pr-preview && git push origin --delete test-pr-preview` + +## 5. Common Issues and Solutions + +### Issue: 404 on Main URL + +**Problem:** `https://platform-mesh.github.io/main/` returns 404 + +**Check:** +1. Is GitHub Pages enabled? (Settings → Pages) +2. Is it deploying from `gh-pages` branch? +3. Did the workflow complete successfully? +4. Wait a few minutes (DNS propagation) + +**Solution:** +```bash +# Verify gh-pages branch exists and has content +git fetch origin gh-pages +git checkout gh-pages +ls -la main/ +``` + +If `main/` directory doesn't exist, the deployment didn't work. Check workflow logs. + +### Issue: Styling Broken + +**Problem:** Page loads but looks completely unstyled + +**Check:** +1. Open browser DevTools (F12) +2. Go to Network tab +3. Refresh page +4. Look for 404 errors on CSS/JS files + +**Common cause:** Base path mismatch + +**Verify in workflow logs:** +``` +Run npm run build + env: + DOCS_VERSION: main # ← Should show the version +``` + +If `DOCS_VERSION` is empty or wrong, the build had wrong base path. + +### Issue: Assets Not Loading + +**Problem:** Images showing broken icon, CSS not applying + +**Check DevTools console:** +- Are asset URLs correct? Should be `/main/assets/...` +- Are assets returning 404? + +**Verify on gh-pages branch:** +```bash +git checkout gh-pages +ls -la main/assets/ +# Should show: app.xxx.js, chunks/, etc. +``` + +### Issue: Version Selector Not Working + +**Problem:** Dropdown shows but clicking doesn't navigate + +**On main version:** +1. Open `https://platform-mesh.github.io/main/` +2. Open DevTools → Console +3. Check for JavaScript errors +4. Click dropdown +5. Select "v0.1" + +**If 404 occurs:** +- Verify `release-0.1` branch was deployed +- Check `https://platform-mesh.github.io/release-0.1/` loads independently +- Check gh-pages branch has `release-0.1/` directory + +### Issue: Workflow Not Triggering + +**Problem:** Push to branch doesn't trigger deployment + +**Check workflow file on that branch:** +```bash +git checkout release-0.1 +cat .github/workflows/pages.yaml +``` + +The workflow file must exist on the branch for it to trigger! + +**If missing:** +```bash +# Merge the workflow changes to the release branch +git checkout release-0.1 +git merge main .github/workflows/pages.yaml +git commit -m "Add versioning workflow" +git push origin release-0.1 +``` + +## 6. GitHub Pages Settings + +Verify your GitHub Pages configuration: + +1. Go to repository **Settings** +2. Scroll to **Pages** section (under "Code and automation") +3. **Source:** Should be "Deploy from a branch" +4. **Branch:** Should be `gh-pages` and `/ (root)` +5. **Custom domain:** (optional, leave blank if not using) + +**Important:** The URL shown there is just `https://platform-mesh.github.io/`, but your docs are at: +- `https://platform-mesh.github.io/main/` +- `https://platform-mesh.github.io/release-0.1/` + +The root URL (`https://platform-mesh.github.io/`) might show a directory listing or 404 unless you add an index.html there. + +## 7. View Deployment History + +You can see all deployments in the Actions history: + +1. Go to **Actions** tab +2. Filter by workflow: "pages" +3. See history of all deployments +4. Click any run to see: + - Which branch triggered it + - What version was built + - Deployment success/failure + - Full logs + +## 8. Manual Verification Checklist + +Use this checklist after each deployment: + +**Main Version (`/main/`):** +- [ ] Homepage loads +- [ ] Navigation works (Home, Overview, Scenarios) +- [ ] Version dropdown appears +- [ ] Version dropdown shows all versions +- [ ] Styling is correct +- [ ] Images load +- [ ] Links work correctly +- [ ] Search works + +**Release Version (`/release-0.1/`):** +- [ ] Homepage loads +- [ ] Navigation works +- [ ] Version dropdown appears +- [ ] Version dropdown shows all versions +- [ ] Content matches expected release version + +**Version Switching:** +- [ ] Can switch from main to release +- [ ] Can switch from release to main +- [ ] Current page path is preserved when switching +- [ ] No 404 errors when switching + +**PR Previews:** +- [ ] PR triggers workflow +- [ ] Bot comments with preview URL +- [ ] Preview URL loads correctly +- [ ] Shows PR changes +- [ ] Independent from version deployments + +## 9. Debugging Commands + +If something isn't working, use these commands: + +**Check deployed content on gh-pages:** +```bash +# Clone just the gh-pages branch +git clone -b gh-pages https://github.com/platform-mesh/platform-mesh.github.io.git gh-pages-check +cd gh-pages-check +ls -la +# Should see: main/, release-0.1/, pr-preview/, etc. +``` + +**Check recent commits on gh-pages:** +```bash +git fetch origin gh-pages +git log origin/gh-pages --oneline -10 +# Shows recent deployments +``` + +**Compare two versions:** +```bash +git checkout gh-pages +diff -r main/ release-0.1/ +# Shows differences between versions +``` + +**Check file sizes:** +```bash +git checkout gh-pages +du -sh main/ release-0.1/ +# Both should be similar size (a few MB) +``` + +## 10. Success Indicators + +Your deployment is successful when: + +✅ **Workflow Status:** +- All workflows complete with green checkmarks +- No errors in logs +- "Deploy to GitHub Pages" step succeeds + +✅ **Branch Structure:** +- `gh-pages` branch exists +- Contains `main/` directory +- Contains `release-X.Y/` directories (if created) +- Each directory has `index.html` and `assets/` + +✅ **URLs Work:** +- `https://platform-mesh.github.io/main/` → loads correctly +- `https://platform-mesh.github.io/release-0.1/` → loads correctly +- No 404 errors + +✅ **Functionality Works:** +- Version selector appears +- Version switching works +- All navigation links work +- Images and assets load +- Search functionality works + +✅ **PR Previews Work:** +- PRs trigger deployments +- Preview URLs load correctly +- Independent from version deployments + +## Summary + +The deployment creates this structure on the `gh-pages` branch: + +``` +gh-pages/ +├── main/ ← Main branch deployment +│ ├── index.html +│ └── assets/ +├── release-0.1/ ← Release branch deployment +│ ├── index.html +│ └── assets/ +└── pr-preview/ ← PR preview deployments + └── pr-123/ +``` + +Each directory is independently deployed and served by GitHub Pages at its corresponding URL path. + +**The `target-folder` parameter in the workflow is what creates these subdirectories automatically!** From a8a6d5964fe060c61ed38f5aa8bcf90c34daae97 Mon Sep 17 00:00:00 2001 From: Mirza Kopic Date: Wed, 29 Oct 2025 15:12:36 +0100 Subject: [PATCH 2/4] fix broken link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 524c8a2..f9b2106 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ suggestions, improvements, or bug fixes, please follow these steps: ## Deployment (local and github) -For detailed documentation on versioning, local testing, and GitHub Pages deployment, see the [how-to-deploy](how-to-deploy/) folder: +For detailed documentation on versioning, local testing, and GitHub Pages deployment, see the documentation: - [Deployment How-To Guide](how-to-deploy/how-to.md) - Complete guide for local testing, version switching, and deploying to GitHub Pages - [Verifying Deployment](how-to-deploy/verify-deployment.md) - Step-by-step verification checklist and troubleshooting From 8791c42653c70cde200660fd044151dd87bcf7c1 Mon Sep 17 00:00:00 2001 From: Mirza Kopic Date: Wed, 29 Oct 2025 16:07:17 +0100 Subject: [PATCH 3/4] fix: dont display version selector in pr-preview --- .gitignore | 3 ++- .vitepress/theme/components/VersionSelector.vue | 15 ++++++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 4b7990c..5ce3213 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ public/.DS_Store .DS_Store CLAUDE.md -.claude/ \ No newline at end of file +.claude/ +test-deploy/ \ No newline at end of file diff --git a/.vitepress/theme/components/VersionSelector.vue b/.vitepress/theme/components/VersionSelector.vue index fc826ce..d5823d3 100644 --- a/.vitepress/theme/components/VersionSelector.vue +++ b/.vitepress/theme/components/VersionSelector.vue @@ -1,5 +1,6 @@