mirror of
https://github.com/BillyOutlast/posthog.git
synced 2026-02-04 03:01:23 +01:00
feat(docs): move some docs to posthog.com published (#40256)
This commit is contained in:
Julian Bez
61
.github/scripts/comment-pr-preview.js
vendored
Executable file
61
.github/scripts/comment-pr-preview.js
vendored
Executable file
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
// Post Vercel-style preview comment on PR
|
||||
// Requires: github, context from actions/github-script
|
||||
// Args: prNumber, triggerStatus, deploymentUrl, deploymentId
|
||||
|
||||
module.exports = async ({github, context, prNumber, triggerStatus, deploymentUrl, deploymentId}) => {
|
||||
const commentHash = `[docs-preview]: #docs-preview-${prNumber}`;
|
||||
|
||||
// Delete old preview comments by finding our hash
|
||||
const comments = await github.rest.issues.listComments({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: prNumber
|
||||
});
|
||||
|
||||
for (const comment of comments.data) {
|
||||
if (comment.user.login === 'github-actions[bot]' && comment.body.includes('[docs-preview]:')) {
|
||||
await github.rest.issues.deleteComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
comment_id: comment.id
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Format timestamp like Vercel (UTC)
|
||||
const now = new Date();
|
||||
const timestamp = now.toLocaleString('en-US', {
|
||||
month: 'short',
|
||||
day: 'numeric',
|
||||
year: 'numeric',
|
||||
hour: 'numeric',
|
||||
minute: '2-digit',
|
||||
hour12: true,
|
||||
timeZone: 'UTC'
|
||||
});
|
||||
|
||||
let message = '';
|
||||
|
||||
if (triggerStatus === 'success') {
|
||||
const previewUrl = deploymentUrl || 'https://posthog.com';
|
||||
const inspectorUrl = deploymentId ? `https://vercel.com/post-hog/posthog/${deploymentId}` : 'https://vercel.com/post-hog/posthog';
|
||||
|
||||
message = `${commentHash}\nDocs from this PR will be published at posthog.com\n\n` +
|
||||
`| Project | Deployment | Preview | Updated (UTC) |\n` +
|
||||
`| :--- | :----- | :------ | :------ |\n` +
|
||||
`| [posthog.com](${inspectorUrl}) | 🤷 Unknown | [Preview](${previewUrl}) | ${timestamp} |\n\n` +
|
||||
`*Preview will be ready in ~10 minutes. Click Preview link above to access docs at \`/handbook/engineering/\`*`;
|
||||
} else {
|
||||
message = `${commentHash}\n⚠️ **Docs Preview Build Failed**\n\n` +
|
||||
`Preview build could not be triggered. Check the [GitHub Action logs](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) for details.`;
|
||||
}
|
||||
|
||||
await github.rest.issues.createComment({
|
||||
issue_number: prNumber,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: message
|
||||
});
|
||||
};
|
||||
56
.github/scripts/trigger-vercel-preview.sh
vendored
Executable file
56
.github/scripts/trigger-vercel-preview.sh
vendored
Executable file
@@ -0,0 +1,56 @@
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Trigger Vercel preview build via API
|
||||
# Args: $1 = PR branch name or ref name
|
||||
|
||||
if [ -z "$VERCEL_TOKEN" ] || [ -z "$VERCEL_TEAM_ID" ] || [ -z "$VERCEL_PROJECT_ID" ]; then
|
||||
echo "⚠️ Vercel secrets not configured, skipping"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
PR_BRANCH="$1"
|
||||
|
||||
echo "📢 Triggering Vercel deployment for posthog.com@master (gatsby-source-git)"
|
||||
echo " Monorepo branch: $PR_BRANCH (per-deployment env)"
|
||||
|
||||
PAYLOAD='{
|
||||
"name": "posthog-com",
|
||||
"project": "'"$VERCEL_PROJECT_ID"'",
|
||||
"gitSource": {
|
||||
"type": "github",
|
||||
"repoId": "260550412",
|
||||
"ref": "master"
|
||||
},
|
||||
"build": {
|
||||
"env": {
|
||||
"GATSBY_POSTHOG_BRANCH": "'"$PR_BRANCH"'"
|
||||
}
|
||||
}
|
||||
}'
|
||||
|
||||
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "https://api.vercel.com/v13/deployments?teamId=${VERCEL_TEAM_ID}" \
|
||||
-H "Authorization: Bearer $VERCEL_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$PAYLOAD")
|
||||
|
||||
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
|
||||
BODY=$(echo "$RESPONSE" | head -n-1)
|
||||
|
||||
if [ "$HTTP_CODE" -eq 200 ] || [ "$HTTP_CODE" -eq 201 ]; then
|
||||
DEPLOYMENT_URL=$(echo "$BODY" | jq -r '.url // empty')
|
||||
DEPLOYMENT_ID=$(echo "$BODY" | jq -r '.id // empty')
|
||||
echo "✅ Successfully triggered Vercel preview build"
|
||||
echo "trigger_status=success" >> "$GITHUB_OUTPUT"
|
||||
if [ -n "$DEPLOYMENT_URL" ]; then
|
||||
echo " Preview URL: https://${DEPLOYMENT_URL}"
|
||||
echo "deployment_url=https://${DEPLOYMENT_URL}" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
if [ -n "$DEPLOYMENT_ID" ]; then
|
||||
echo "deployment_id=${DEPLOYMENT_ID}" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
else
|
||||
echo "❌ Failed to trigger preview build (HTTP $HTTP_CODE)"
|
||||
echo "$BODY" | jq '.' 2>/dev/null || echo "$BODY"
|
||||
echo "trigger_status=failed" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
97
.github/workflows/docs-preview-trigger.yml
vendored
Normal file
97
.github/workflows/docs-preview-trigger.yml
vendored
Normal file
@@ -0,0 +1,97 @@
|
||||
name: Trigger Docs Preview Build
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'docs/published/**'
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
paths:
|
||||
- 'docs/published/**'
|
||||
|
||||
permissions:
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
trigger-preview:
|
||||
name: Trigger posthog.com preview build
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Trigger Vercel build
|
||||
id: trigger-build
|
||||
env:
|
||||
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
|
||||
VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
|
||||
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
|
||||
run: .github/scripts/trigger-vercel-preview.sh "${{ github.event.pull_request.head.ref || github.ref_name }}"
|
||||
|
||||
- name: Comment on PR
|
||||
if: github.event_name == 'pull_request'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const commentFn = require('./.github/scripts/comment-pr-preview.js');
|
||||
await commentFn({
|
||||
github,
|
||||
context,
|
||||
prNumber: ${{ github.event.pull_request.number }},
|
||||
triggerStatus: "${{ steps.trigger-build.outputs.trigger_status }}",
|
||||
deploymentUrl: "${{ steps.trigger-build.outputs.deployment_url }}",
|
||||
deploymentId: "${{ steps.trigger-build.outputs.deployment_id }}"
|
||||
});
|
||||
|
||||
validate-docs:
|
||||
name: Validate docs structure
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Check frontmatter in published docs
|
||||
run: |
|
||||
echo "Checking for required frontmatter in published docs..."
|
||||
|
||||
MISSING_FRONTMATTER=0
|
||||
|
||||
# Find all markdown/mdx files in published docs
|
||||
for file in docs/published/**/*.{md,mdx}; do
|
||||
if [ -f "$file" ]; then
|
||||
# Check if file starts with ---
|
||||
if ! head -1 "$file" | grep -q "^---"; then
|
||||
echo "❌ Missing frontmatter in: $file"
|
||||
MISSING_FRONTMATTER=1
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
if [ $MISSING_FRONTMATTER -eq 1 ]; then
|
||||
echo "Some files are missing required frontmatter. All docs in /docs/published/ must have YAML frontmatter."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ All published docs have frontmatter"
|
||||
|
||||
- name: Verify internal docs not in published
|
||||
run: |
|
||||
echo "Verifying internal docs are not accidentally in published..."
|
||||
|
||||
if find docs/published -name "*internal*" -o -name "*private*" -o -name "*secret*" 2>/dev/null | grep -q .; then
|
||||
echo "❌ Found internal/private docs in published directory!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ No internal docs found in published directory"
|
||||
|
||||
- name: Check for broken relative links
|
||||
run: |
|
||||
echo "Checking for obvious link issues..."
|
||||
|
||||
# Check for links pointing outside /published/
|
||||
if grep -r '\[.*\](\.\.\/\.\./' docs/published/ 2>/dev/null; then
|
||||
echo "⚠️ Found links that go outside /published/ directory - verify these are intentional"
|
||||
else
|
||||
echo "✅ Links appear to be within /published/ directory"
|
||||
fi
|
||||
52
docs/README.md
Normal file
52
docs/README.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# PostHog Documentation
|
||||
|
||||
Developer-focused documentation alongside code. Update docs in the same PR as your code changes.
|
||||
|
||||
## Structure
|
||||
|
||||
### `published/` - Published on posthog.com
|
||||
|
||||
Documentation published to https://posthog.com/handbook/engineering/ when merged to master:
|
||||
|
||||
- Architecture guides
|
||||
- Contributing guides
|
||||
- Engineering practices
|
||||
|
||||
**When to use**: Documentation that external users or contributors need.
|
||||
|
||||
### `internal/` - GitHub-only
|
||||
|
||||
Documentation that stays in the repository:
|
||||
|
||||
- Development workflows
|
||||
- Migration patterns
|
||||
- Team processes
|
||||
|
||||
**When to use**: Knowledge useful for the team but not for external users. We're open source, so "internal" means GitHub-only rather than truly private.
|
||||
|
||||
## Publishing Flow
|
||||
|
||||
```text
|
||||
Engineer creates PR with /docs/published/** changes
|
||||
↓
|
||||
GitHub Action triggers posthog.com preview build
|
||||
↓
|
||||
Preview URL posted to PR
|
||||
↓
|
||||
Merge to master
|
||||
↓
|
||||
Docs go live on posthog.com
|
||||
```
|
||||
|
||||
The posthog.com Gatsby build uses gatsby-source-git to clone this monorepo and pull files from `/docs/published/` during the build process.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- All published docs must have YAML frontmatter
|
||||
- Use relative links between docs: `../contributing/index.md`
|
||||
- Docs about PostHog internals → here
|
||||
- User product docs and tutorials → posthog.com repo
|
||||
|
||||
## Setup
|
||||
|
||||
For posthog.com team setting up the integration, see the PRs in PostHog/posthog.com repo.
|
||||
@@ -1,4 +1,8 @@
|
||||
# PostHog Isolated Development Environments with Flox
|
||||
---
|
||||
title: Isolated Development with Flox
|
||||
showTitle: true
|
||||
noindex: true
|
||||
---
|
||||
|
||||
This guide explains how to create isolated PostHog development environments using Flox and Git worktrees for seamless branch switching.
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
# Safe Django Migration Guide
|
||||
---
|
||||
title: Safe Django Migrations
|
||||
showTitle: true
|
||||
noindex: true
|
||||
---
|
||||
|
||||
This guide explains how to safely perform dangerous Django migration operations in production with PostgreSQL. Each section covers a risky operation and provides step-by-step instructions for the safe approach.
|
||||
|
||||
Reference in New Issue
Block a user