Add comprehensive TQL language documentation #274
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Prevent Manual Updates | |
| on: | |
| pull_request: | |
| types: [opened, synchronize, reopened] | |
| permissions: | |
| contents: read | |
| pull-requests: write | |
| jobs: | |
| check: | |
| name: Check | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Get changed files | |
| id: changed-files | |
| run: | | |
| # Get list of changed files in this PR | |
| git fetch origin ${{ github.event.pull_request.base.ref }} | |
| changed_files=$(git diff --name-only origin/${{ github.event.pull_request.base.ref }}...HEAD) | |
| echo "Changed files:" | |
| echo "$changed_files" | |
| echo "changed_files<<EOF" >> $GITHUB_OUTPUT | |
| echo "$changed_files" >> $GITHUB_OUTPUT | |
| echo "EOF" >> $GITHUB_OUTPUT | |
| - name: Check for auto-updated files | |
| id: check-files | |
| run: | | |
| # Define exact paths and patterns for auto-updated files | |
| auto_updated_files=( | |
| # Tenzir Node auto-updated files (exact paths) | |
| "src/content/apis/openapi.node.yaml" | |
| "src/content/apis/openapi.platform.yaml" | |
| "tenzir.yaml.example" | |
| "src/content/docs/reference/functions.mdx" | |
| "src/content/docs/reference/operators.mdx" | |
| ) | |
| auto_updated_directories=( | |
| # Tenzir Node auto-updated directories | |
| "src/content/docs/reference/functions/" | |
| "src/content/docs/reference/operators/" | |
| # Changelog files (generated by changelog script) | |
| "src/content/docs/changelog/node" | |
| "src/content/docs/changelog/platform" | |
| ) | |
| changed_files="${{ steps.changed-files.outputs.changed_files }}" | |
| modified_auto_files=() | |
| # Check each changed file against auto-updated files and directories | |
| while IFS= read -r file; do | |
| if [[ -z "$file" ]]; then | |
| continue | |
| fi | |
| # Check exact file matches | |
| for auto_file in "${auto_updated_files[@]}"; do | |
| if [[ "$file" == "$auto_file" ]]; then | |
| modified_auto_files+=("$file") | |
| break 2 | |
| fi | |
| done | |
| # Check directory matches | |
| for auto_dir in "${auto_updated_directories[@]}"; do | |
| if [[ "$file" == "$auto_dir"* ]]; then | |
| modified_auto_files+=("$file") | |
| break | |
| fi | |
| done | |
| done <<< "$changed_files" | |
| if [[ ${#modified_auto_files[@]} -gt 0 ]]; then | |
| echo "found_violations=true" >> $GITHUB_OUTPUT | |
| echo "violated_files<<EOF" >> $GITHUB_OUTPUT | |
| printf '%s\n' "${modified_auto_files[@]}" >> $GITHUB_OUTPUT | |
| echo "EOF" >> $GITHUB_OUTPUT | |
| else | |
| echo "found_violations=false" >> $GITHUB_OUTPUT | |
| fi | |
| - name: Check for existing marker comment | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const { data: comments } = await github.rest.issues.listComments({ | |
| issue_number: context.issue.number, | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| }); | |
| const markerComment = comments.find(comment => | |
| comment.body.includes('<!-- prevent-manual-updates-marker -->') | |
| ); | |
| if (markerComment) { | |
| core.setOutput('existing_comment_id', markerComment.id); | |
| core.setOutput('has_existing_comment', 'true'); | |
| } else { | |
| core.setOutput('has_existing_comment', 'false'); | |
| } | |
| id: check-existing-comment | |
| - name: Comment on PR if violations found and no existing comment | |
| if: steps.check-files.outputs.found_violations == 'true' && steps.check-existing-comment.outputs.has_existing_comment == 'false' | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const violatedFiles = `${{ steps.check-files.outputs.violated_files }}`.split('\n').filter(f => f.trim()); | |
| const comment = `<!-- prevent-manual-updates-marker --> | |
| > [!WARNING] | |
| > | |
| > This pull request modifies files that are automatically updated by our CI system. Manual changes to these files will be overwritten the next time the update workflow runs. | |
| **Modified auto-updated files:** | |
| ${violatedFiles.map(f => `- \`${f}\``).join('\n')} | |
| **What to do:** | |
| 1. **For documentation content changes:** Make your changes in the upstream repositories: | |
| - **Functions/Operators:** Update files in the [tenzir/tenzir](https://github.com/tenzir/tenzir) repository | |
| - **Platform CLI:** Update files in the [tenzir/platform](https://github.com/tenzir/platform) repository | |
| 2. **For file structure or generation logic changes:** Modify the update scripts or workflow in this repository | |
| 3. **Remove the manual changes** from this PR and revert these files to their original state | |
| The following files and directories are automatically updated and should **never** be manually edited: | |
| **Files:** | |
| - \`src/content/apis/openapi.node.yaml\` (Tenzir Node API spec) | |
| - \`src/content/apis/openapi.platform.yaml\` (Tenzir Platform API spec) | |
| - \`tenzir.yaml.example\` (Example configuration) | |
| - \`src/content/docs/reference/functions.mdx\` (Generated functions overview) | |
| - \`src/content/docs/reference/operators.mdx\` (Generated operators overview) | |
| - \`src/content/docs/reference/platform-cli.mdx\` (Platform CLI reference) | |
| **Directories:** | |
| - \`src/content/docs/reference/functions/\` (Individual function docs) | |
| - \`src/content/docs/reference/operators/\` (Individual operator docs) | |
| - \`src/content/docs/reference/changelog/node/\` (Tenzir Node changelog entries) | |
| - \`src/content/docs/reference/changelog/platform/\` (Tenzir Platform changelog entries) | |
| See our [documentation contribution guide](https://docs.tenzir.com/guides/contribution/documentation#auto-updated-files) for more details. | |
| *This comment will be removed automatically when this problem is resolved.*`; | |
| github.rest.issues.createComment({ | |
| issue_number: context.issue.number, | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| body: comment | |
| }); | |
| - name: Remove existing comment if violations are resolved | |
| if: steps.check-files.outputs.found_violations == 'false' && steps.check-existing-comment.outputs.has_existing_comment == 'true' | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| await github.rest.issues.deleteComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| comment_id: ${{ steps.check-existing-comment.outputs.existing_comment_id }} | |
| }); | |
| - name: Fail if violations found | |
| if: steps.check-files.outputs.found_violations == 'true' | |
| run: | | |
| echo "❌ This PR modifies auto-updated files. Please see the comment above for instructions." | |
| echo "Violated files:" | |
| echo "${{ steps.check-files.outputs.violated_files }}" | |
| exit 1 | |
| - name: Success message | |
| if: steps.check-files.outputs.found_violations == 'false' | |
| run: | | |
| echo "✅ No auto-updated files were modified in this PR." |