|
| 1 | +name: Documentation edit helper |
| 2 | + |
| 3 | +on: |
| 4 | + pull_request: |
| 5 | + types: |
| 6 | + - opened |
| 7 | + - synchronize |
| 8 | + paths: |
| 9 | + - 'packages/*/_dev/build/docs/README.md' |
| 10 | + |
| 11 | +jobs: |
| 12 | + help-with-docs: |
| 13 | + if: | |
| 14 | + github.actor != 'github-actions[bot]' && |
| 15 | + (startsWith(github.head_ref, 'docs-enhancement/') || startsWith(github.head_ref, 'docs-bugfix/')) |
| 16 | + runs-on: ubuntu-latest |
| 17 | + permissions: |
| 18 | + contents: read |
| 19 | + pull-requests: write |
| 20 | + |
| 21 | + steps: |
| 22 | + - name: Checkout repository |
| 23 | + uses: actions/checkout@v5 |
| 24 | + |
| 25 | + - name: Analyze documentation changes and generate commands |
| 26 | + id: analyze |
| 27 | + env: |
| 28 | + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
| 29 | + run: | |
| 30 | + echo "🔍 Analyzing documentation changes..." |
| 31 | + |
| 32 | + PR_NUMBER=${{ github.event.pull_request.number }} |
| 33 | + |
| 34 | + # Get changed files directly from PR |
| 35 | + if ! PR_FILES=$(gh pr view $PR_NUMBER --json files -q '.files[].path' 2>/dev/null); then |
| 36 | + echo "Error: Failed to fetch PR files" |
| 37 | + exit 1 |
| 38 | + fi |
| 39 | + CHANGED_DOCS=$(echo "$PR_FILES" | grep '^packages/.*/_dev/build/docs/README\.md$' || true) |
| 40 | + |
| 41 | + if [ -z "$CHANGED_DOCS" ]; then |
| 42 | + echo "no_docs_changes=true" >> $GITHUB_OUTPUT |
| 43 | + exit 0 |
| 44 | + fi |
| 45 | + |
| 46 | + # Determine change type from branch name |
| 47 | + CHANGE_TYPE="enhancement" |
| 48 | + VERSION_BUMP="minor" |
| 49 | + LABEL="enhancement" |
| 50 | + if [[ "${{ github.head_ref }}" =~ ^docs-bugfix/ ]]; then |
| 51 | + CHANGE_TYPE="bugfix" |
| 52 | + VERSION_BUMP="patch" |
| 53 | + LABEL="bugfix" |
| 54 | + fi |
| 55 | + |
| 56 | + # Get custom changelog description from PR body |
| 57 | + if ! PR_BODY=$(gh pr view $PR_NUMBER --json body -q '.body // ""' 2>/dev/null); then |
| 58 | + echo "Warning: Failed to fetch PR body, using default changelog description" |
| 59 | + PR_BODY="" |
| 60 | + fi |
| 61 | + |
| 62 | + CHANGELOG_DESC="Improve documentation" |
| 63 | + if [ "$CHANGE_TYPE" = "bugfix" ]; then |
| 64 | + CHANGELOG_DESC="Fix documentation" |
| 65 | + fi |
| 66 | + |
| 67 | + # Check for custom changelog description in PR body |
| 68 | + if echo "$PR_BODY" | grep -qi "^changelog:"; then |
| 69 | + CUSTOM_DESC=$(echo "$PR_BODY" | grep -i "^changelog:" | sed 's/^changelog://i' | xargs) |
| 70 | + if [ -n "$CUSTOM_DESC" ]; then |
| 71 | + # Escape quotes and special characters for safe command generation |
| 72 | + CHANGELOG_DESC=$(echo "$CUSTOM_DESC" | sed 's/"/\\"/g' | sed "s/'/\\'/g") |
| 73 | + fi |
| 74 | + fi |
| 75 | + |
| 76 | + echo "change_type=$CHANGE_TYPE" >> $GITHUB_OUTPUT |
| 77 | + echo "version_bump=$VERSION_BUMP" >> $GITHUB_OUTPUT |
| 78 | + echo "label=$LABEL" >> $GITHUB_OUTPUT |
| 79 | + echo "changelog_desc=$CHANGELOG_DESC" >> $GITHUB_OUTPUT |
| 80 | + |
| 81 | + # Get all changed files from PR to check what's already updated |
| 82 | + # Reuse the PR_FILES we already fetched to avoid another API call |
| 83 | + ALL_CHANGED_FILES="$PR_FILES" |
| 84 | + |
| 85 | + # Find packages that need updates vs already done |
| 86 | + PACKAGES_NEEDING_UPDATE="" |
| 87 | + PACKAGES_ALREADY_DONE="" |
| 88 | + |
| 89 | + while IFS= read -r doc_file; do |
| 90 | + [ -z "$doc_file" ] && continue |
| 91 | + |
| 92 | + PACKAGE=$(echo "$doc_file" | sed 's|^packages/\([^/]*\)/.*|\1|') |
| 93 | + |
| 94 | + # Check if manifest.yml or changelog.yml are in the changed files |
| 95 | + MANIFEST_CHANGED=$(echo "$ALL_CHANGED_FILES" | grep "^packages/$PACKAGE/manifest.yml$" || true) |
| 96 | + CHANGELOG_CHANGED=$(echo "$ALL_CHANGED_FILES" | grep "^packages/$PACKAGE/changelog.yml$" || true) |
| 97 | + |
| 98 | + if [ -z "$MANIFEST_CHANGED" ] && [ -z "$CHANGELOG_CHANGED" ]; then |
| 99 | + PACKAGES_NEEDING_UPDATE="$PACKAGES_NEEDING_UPDATE $PACKAGE" |
| 100 | + else |
| 101 | + PACKAGES_ALREADY_DONE="$PACKAGES_ALREADY_DONE $PACKAGE" |
| 102 | + fi |
| 103 | + |
| 104 | + done <<< "$CHANGED_DOCS" |
| 105 | + |
| 106 | + echo "packages_needing_update=$PACKAGES_NEEDING_UPDATE" >> $GITHUB_OUTPUT |
| 107 | + echo "packages_already_done=$PACKAGES_ALREADY_DONE" >> $GITHUB_OUTPUT |
| 108 | +
|
| 109 | + - name: Comment with exact commands (same-repo PRs) |
| 110 | + if: steps.analyze.outputs.packages_needing_update && github.event.pull_request.head.repo.fork == false |
| 111 | + env: |
| 112 | + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
| 113 | + run: | |
| 114 | + PACKAGES="${{ steps.analyze.outputs.packages_needing_update }}" |
| 115 | + CHANGE_TYPE="${{ steps.analyze.outputs.change_type }}" |
| 116 | + VERSION_BUMP="${{ steps.analyze.outputs.version_bump }}" |
| 117 | + CHANGELOG_DESC="${{ steps.analyze.outputs.changelog_desc }}" |
| 118 | + PR_NUMBER=${{ github.event.pull_request.number }} |
| 119 | + |
| 120 | + # Create clean package list for the for loop |
| 121 | + PACKAGE_LIST=$(echo $PACKAGES | xargs) |
| 122 | + |
| 123 | + # Safety check for empty package list |
| 124 | + if [ -z "$PACKAGE_LIST" ]; then |
| 125 | + echo "No packages found, skipping comment" |
| 126 | + exit 0 |
| 127 | + fi |
| 128 | + |
| 129 | + COMMENT_FILE=$(mktemp) |
| 130 | + { |
| 131 | + echo "Please run these commands to update changelogs and build docs:" |
| 132 | + echo "" |
| 133 | + echo '```bash' |
| 134 | + echo "for pkg in ${PACKAGE_LIST}; do" |
| 135 | + echo ' cd packages/$pkg' |
| 136 | + echo " elastic-package changelog add --type $CHANGE_TYPE --description \"$CHANGELOG_DESC\" --link \"https://github.com/${{ github.repository }}/pull/$PR_NUMBER\" --next $VERSION_BUMP" |
| 137 | + echo " elastic-package build" |
| 138 | + echo " cd ../.." |
| 139 | + echo "done" |
| 140 | + echo "git add -u" |
| 141 | + echo "git commit -m \"docs: update changelogs and build documentation\"" |
| 142 | + echo "git push" |
| 143 | + echo '```' |
| 144 | + echo "" |
| 145 | + echo "Prerequisite: \`go install github.com/elastic/elastic-package\`" |
| 146 | + } > "$COMMENT_FILE" |
| 147 | +
|
| 148 | + if [ -n "${{ steps.analyze.outputs.packages_already_done }}" ]; then |
| 149 | + echo "" >> "$COMMENT_FILE" |
| 150 | + echo "Note: These packages already updated: \`${{ steps.analyze.outputs.packages_already_done }}\`" >> "$COMMENT_FILE" |
| 151 | + fi |
| 152 | +
|
| 153 | + if ! gh pr comment "$PR_NUMBER" --body-file "$COMMENT_FILE"; then |
| 154 | + { |
| 155 | + echo "## 📋 Documentation follow-up" |
| 156 | + echo |
| 157 | + cat "$COMMENT_FILE" |
| 158 | + } >> "$GITHUB_STEP_SUMMARY" |
| 159 | + fi |
| 160 | +
|
| 161 | + - name: Show commands in summary (fork PRs) |
| 162 | + if: steps.analyze.outputs.packages_needing_update && github.event.pull_request.head.repo.fork == true |
| 163 | + run: | |
| 164 | + PACKAGES="${{ steps.analyze.outputs.packages_needing_update }}" |
| 165 | + CHANGE_TYPE="${{ steps.analyze.outputs.change_type }}" |
| 166 | + VERSION_BUMP="${{ steps.analyze.outputs.version_bump }}" |
| 167 | + CHANGELOG_DESC="${{ steps.analyze.outputs.changelog_desc }}" |
| 168 | + PR_NUMBER=${{ github.event.pull_request.number }} |
| 169 | +
|
| 170 | + PACKAGE_LIST=$(echo $PACKAGES | xargs) |
| 171 | +
|
| 172 | + if [ -z "$PACKAGE_LIST" ]; then |
| 173 | + exit 0 |
| 174 | + fi |
| 175 | +
|
| 176 | + { |
| 177 | + echo "## 📋 Documentation follow-up" |
| 178 | + echo "" |
| 179 | + echo "Please run these commands to update changelogs and build docs:" |
| 180 | + echo "" |
| 181 | + echo '```bash' |
| 182 | + echo "for pkg in ${PACKAGE_LIST}; do" |
| 183 | + echo ' cd packages/$pkg' |
| 184 | + echo " elastic-package changelog add --type $CHANGE_TYPE --description \"$CHANGELOG_DESC\" --link \"https://github.com/${{ github.repository }}/pull/$PR_NUMBER\" --next $VERSION_BUMP" |
| 185 | + echo " elastic-package build" |
| 186 | + echo " cd ../.." |
| 187 | + echo "done" |
| 188 | + echo "git add -u" |
| 189 | + echo "git commit -m \"docs: update changelogs and build documentation\"" |
| 190 | + echo "git push" |
| 191 | + echo '```' |
| 192 | + echo "" |
| 193 | + echo "Prerequisite: \`go install github.com/elastic/elastic-package\`" |
| 194 | + if [ -n "${{ steps.analyze.outputs.packages_already_done }}" ]; then |
| 195 | + echo "" |
| 196 | + echo "Note: These packages already updated: \`${{ steps.analyze.outputs.packages_already_done }}\`" |
| 197 | + fi |
| 198 | + } >> "$GITHUB_STEP_SUMMARY" |
| 199 | +
|
| 200 | + - name: Add labels |
| 201 | + run: | |
| 202 | + echo "Please add the following labels — '${{ steps.analyze.outputs.label }}' and 'documentation'" >> "$GITHUB_STEP_SUMMARY" |
| 203 | +
|
| 204 | + - name: Handle edge cases |
| 205 | + if: steps.analyze.outputs.no_docs_changes == 'true' || (steps.analyze.outputs.packages_needing_update == '' && steps.analyze.outputs.packages_already_done != '') |
| 206 | + run: | |
| 207 | + if [ "${{ steps.analyze.outputs.no_docs_changes }}" = "true" ]; then |
| 208 | + MESSAGE="No documentation files (packages/*/_dev/build/docs/README.md) were changed in this PR." |
| 209 | + else |
| 210 | + MESSAGE="All packages with documentation changes already have updated changelogs and manifests." |
| 211 | + fi |
| 212 | + |
| 213 | + echo "## 📚 Documentation Status |
| 214 | +
|
| 215 | + $MESSAGE |
| 216 | +
|
| 217 | + Your PR is ready for review! 🎉" >> "$GITHUB_STEP_SUMMARY" |
0 commit comments