Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions .github/workflows/remind-sync-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
name: Remind to Sync Documentation

on:
push:
branches: [master]
paths:
- 'influxdata/**/README.md'

permissions:
contents: read

jobs:
remind-sync:
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 2 # Need previous commit to detect changes

- name: Detect changed plugins
id: detect-changes
run: |
# Get list of changed README files
CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep '^influxdata/.*/README\.md$' | head -10)
Copy link
Preview

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The head -10 limitation arbitrarily caps the number of changed files processed. If more than 10 plugin READMEs are changed in a single commit, some changes won't trigger sync reminders. Consider either removing this limit or making it configurable.

Suggested change
CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep '^influxdata/.*/README\.md$' | head -10)
CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep '^influxdata/.*/README\.md$')

Copilot uses AI. Check for mistakes.


if [[ -z "$CHANGED_FILES" ]]; then
echo "No plugin README files changed"
echo "changed_plugins=" >> $GITHUB_OUTPUT
echo "has_changes=false" >> $GITHUB_OUTPUT
exit 0
fi

echo "Changed files:"
echo "$CHANGED_FILES"

# Extract plugin names from file paths
PLUGIN_NAMES=""
while IFS= read -r file; do
if [[ -n "$file" ]]; then
# Extract plugin name from path: influxdata/plugin_name/README.md -> plugin_name
PLUGIN_NAME=$(echo "$file" | sed 's|influxdata/||' | sed 's|/README\.md||')
if [[ -n "$PLUGIN_NAMES" ]]; then
PLUGIN_NAMES="$PLUGIN_NAMES, $PLUGIN_NAME"
else
PLUGIN_NAMES="$PLUGIN_NAME"
fi
fi
done <<< "$CHANGED_FILES"

echo "Changed plugins: $PLUGIN_NAMES"
echo "changed_plugins=$PLUGIN_NAMES" >> $GITHUB_OUTPUT
echo "has_changes=true" >> $GITHUB_OUTPUT

- name: Create sync reminder comment
if: steps.detect-changes.outputs.has_changes == 'true'
uses: actions/github-script@v7
with:
script: |
const changedPlugins = '${{ steps.detect-changes.outputs.changed_plugins }}';
const commitSha = context.sha;
const shortSha = commitSha.substring(0, 7);

// Build the GitHub issue URL with pre-filled parameters
const baseUrl = 'https://github.com/influxdata/docs-v2/issues/new';
const template = 'sync-plugin-docs.yml';
const title = encodeURIComponent(`Sync plugin docs: ${changedPlugins}`);
const plugins = encodeURIComponent(changedPlugins);
const sourceCommit = encodeURIComponent(commitSha);

const issueUrl = `${baseUrl}?template=${template}&title=${title}&plugins=${plugins}&source_commit=${sourceCommit}`;

// Create the comment body
const commentBody = `📚 **Plugin documentation updated!**

The following plugin READMEs were changed in this commit:
**${changedPlugins}**

## Next Steps

To sync these changes to the InfluxDB documentation site:

### 🚀 [**Click here to create sync request**](${issueUrl})

This will open a pre-filled issue in docs-v2 that will automatically trigger the sync workflow.

### What the sync process does:
1. ✅ Validates your plugin READMEs against template requirements
2. 🔄 Transforms content for docs-v2 compatibility (adds Hugo shortcodes, fixes links)
3. 🖼️ Generates screenshots of the plugin documentation pages
4. 📝 Creates a pull request in docs-v2 ready for review

### Before syncing:
- Ensure your README follows the [README_TEMPLATE.md](https://github.com/influxdata/influxdb3_plugins/blob/master/README_TEMPLATE.md) structure
- Include proper emoji metadata (⚡ triggers, 🏷️ tags, 🔧 compatibility)
- Verify all required sections are present and complete

---
*Commit: ${shortSha} | [View workflow](https://github.com/influxdata/docs-v2/blob/master/helper-scripts/influxdb3-plugins/README.md)*`;

// Create commit comment
await github.rest.repos.createCommitComment({
owner: context.repo.owner,
repo: context.repo.repo,
commit_sha: commitSha,
body: commentBody
});

console.log(`Created sync reminder for plugins: ${changedPlugins}`);
console.log(`Issue URL: ${issueUrl}`);

- name: Log workflow completion
if: steps.detect-changes.outputs.has_changes == 'true'
run: |
echo "✅ Sync reminder created for plugins: ${{ steps.detect-changes.outputs.changed_plugins }}"
echo "🔗 Users can click the link in the commit comment to trigger docs sync"

- name: No changes detected
if: steps.detect-changes.outputs.has_changes == 'false'
run: |
echo "ℹ️ No plugin README files were changed in this commit"
58 changes: 58 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -489,6 +489,51 @@ raise ValueError(
)
```

## Documentation Sync Process

### Syncing Plugin Documentation to docs-v2

When you update plugin READMEs in this repository, they need to be synchronized to the InfluxDB documentation site (docs-v2) to appear on docs.influxdata.com.

#### Automated Sync Workflow

1. **Make your changes** - Update plugin README files following the template structure
2. **Commit and push** - Push your changes to the master branch
3. **Check for reminder** - A workflow will automatically detect README changes and create a commit comment with a sync link
4. **Click sync link** - The comment includes a pre-filled link to create a sync request in docs-v2
5. **Submit request** - This automatically triggers validation, transformation, and PR creation
6. **Review PR** - The resulting PR in docs-v2 includes screenshots and change summaries

#### Manual Sync (Alternative)

You can also manually trigger synchronization:

1. **Navigate to sync form**: [Create sync request](https://github.com/influxdata/docs-v2/issues/new?template=sync-plugin-docs.yml)
2. **Fill in details** - Specify plugin names and source commit
3. **Submit** - The automation workflow handles the rest

#### Sync Requirements

Before syncing, ensure your README:

- ✅ Follows the [README_TEMPLATE.md](README_TEMPLATE.md) structure
- ✅ Includes proper emoji metadata (`⚡` triggers, `🏷️` tags, `🔧` compatibility)
- ✅ Has all required sections with proper formatting
- ✅ Contains working examples with expected output
- ✅ Passes validation (`python scripts/validate_readme.py`)

#### What Gets Transformed

During sync, your README content is automatically transformed for docs-v2:

- **Emoji metadata removed** (already in plugin JSON metadata)
- **Relative links converted** to GitHub URLs
- **Product references enhanced** with Hugo shortcodes (`{{% product-name %}}`)
- **Logging section added** with standard content
- **Support sections updated** with docs-v2 format

Your original README remains unchanged - these transformations only apply to the docs-v2 copy.

## Commit Message Format

### Use conventional commits
Expand All @@ -509,4 +554,17 @@ raise ValueError(
- `test`: Test changes
- `chore`: Maintenance tasks

### Documentation Sync Messages

When making documentation-focused commits, use clear messages that describe what changed:

```bash
# Good commit messages for docs sync
docs(basic_transformation): update configuration parameters and examples
feat(downsampler): add support for custom aggregation functions
fix(notifier): correct email configuration example

# These will trigger sync reminders automatically
```

*These standards are extracted from the [InfluxData Documentation guidelines](https://github.com/influxdata/docs-v2/blob/master/CONTRIBUTING.md).*
Loading