Copilot commented on code in PR #11205: URL: https://github.com/apache/gravitino/pull/11205#discussion_r3296580623
########## docs/lance-rest-server-chart.md: ########## @@ -1,12 +1,12 @@ --- title: "Install Lance REST Server on Kubernetes" -slug: /lance-rest-server-chart -keyword: +slug: "/lance-rest-server-chart" +keyword: " " - Lance REST Server Helm Chart license: "This software is licensed under the Apache License version 2." Review Comment: Frontmatter YAML is invalid: `keyword` is defined as a quoted scalar (`" "`) but then also has a list item on the next indented line. This will break frontmatter parsing in Docusaurus. Make `keyword` consistently a YAML list (e.g., `keyword:` followed by `- ...`) or a single string, but not both. ########## docs/iceberg-rest-engine/trino.md: ########## @@ -185,9 +185,9 @@ FROM <catalog>.<namespace>.<table>; | Supported engines | Trino, Spark, Flink, Daft | Any Iceberg-compatible engine | | Credential vending | Varies | Yes (S3, GCS, OSS, ADLS) | -## Known issues +## Known Issues -### Trino identifiers are not treated as case sensitive +### Trino Identifiers Are Not Treated as Case Sensitive Review Comment: This doc contains two H2 sections both titled "Known Issues" (same heading text). Duplicate H2s will generate duplicate/numbered anchors in Docusaurus and can break existing `#known-issues` links or create ambiguous navigation. Consider merging the sections or renaming one of the headings to keep anchors stable and unique. ########## docs/table-maintenance-service/optimizer-troubleshooting.md: ########## @@ -1,31 +1,31 @@ --- title: "Optimizer Troubleshooting" -slug: /table-maintenance-service/troubleshooting -keyword: table maintenance, optimizer, troubleshooting, spark, strategy -license: This software is licensed under the Apache License version 2. +slug: "/table-maintenance-service/troubleshooting" +keyword: "table maintenance, optimizer, troubleshooting, spark, strategy" +license: "This software is licensed under the Apache License version 2." --- ## `Invalid --type` Use kebab-case values such as `update-statistics`, not `update_statistics`. -## `--statistics-payload and --file-path cannot be used together` +## `--statistics-payload and --file-path Cannot Be Used together` Review Comment: The heading text inside the code span was changed (e.g., `Cannot Be Used together`). Backticked content should remain verbatim because it often matches exact CLI error strings/flags and also affects anchor generation. Please restore the original casing inside the backticks and apply any Title Case changes outside code spans only. ########## docs/trino-connector/catalog-hive.md: ########## @@ -377,7 +379,7 @@ replacing hdfs_user with the appropriate username: ## S3 When using AWS S3 within the Hive catalog, users need to configure the Trino Hive connector's -AWS S3-related properties in the catalog's properteis. Please refer to the documentation +AWS S3-related properties in the catalog's properteis. Refer to the documentation of [Hive connector with Amazon S3](https://trino.io/docs/current/connector/hive-s3.html). Review Comment: The word "properteis" is misspelled; this should be "properties". ########## docs/trino-connector/requirements.md: ########## @@ -1,10 +1,12 @@ --- -title: "Apache Gravitino Trino connector requirements" -slug: /trino-connector/requirements -keyword: gravitino connector trino +title: "Trino Connector Requirements" +slug: "/trino-connector/requirements" +keyword: "gravitino connector trino" license: "This software is licensed under the Apache License version 2." --- +## Introduction + To install and deploy the Apache Gravitino Trino connector, The following environmental setup is necessary: Review Comment: Grammar/capitalization: "..., The following ..." should not capitalize "The" mid-sentence, and "environmental setup" is usually phrased as "environment setup". Consider rewriting the sentence for readability (e.g., split into two sentences or use lowercase after the comma). ########## docs/table-maintenance-service/optimizer-troubleshooting.md: ########## @@ -1,31 +1,31 @@ --- title: "Optimizer Troubleshooting" -slug: /table-maintenance-service/troubleshooting -keyword: table maintenance, optimizer, troubleshooting, spark, strategy -license: This software is licensed under the Apache License version 2. +slug: "/table-maintenance-service/troubleshooting" +keyword: "table maintenance, optimizer, troubleshooting, spark, strategy" +license: "This software is licensed under the Apache License version 2." --- ## `Invalid --type` Use kebab-case values such as `update-statistics`, not `update_statistics`. -## `--statistics-payload and --file-path cannot be used together` +## `--statistics-payload and --file-path Cannot Be Used together` For `local-stats-calculator`, use exactly one of them. -## `requires one of --statistics-payload or --file-path` +## `requires One of --statistics-payload or --file-path` Review Comment: Similarly, this code-span heading was Title Cased (`requires One of ...`). Since it is presented as literal output, keep the backticked text exactly as produced by the CLI/error message to avoid misleading users and changing anchors unexpectedly. ########## scripts/title_h2_audit.py: ########## @@ -0,0 +1,91 @@ +#!/usr/bin/env python3 +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""Find Markdown files where the first body H2 duplicates the frontmatter title.""" +import re +import sys +from pathlib import Path + +TITLE_RE = re.compile(r'^title:\s*["\']?(.*?)["\']?\s*$', re.MULTILINE) +H2_RE = re.compile(r'^##\s+(.+)$', re.MULTILINE) +FRONTMATTER_RE = re.compile(r'^---\n(.*?)\n---\n', re.DOTALL) + + +def normalize(s): + s = s.lower().strip() + s = re.sub(r'[^\w\s]', ' ', s) + s = re.sub(r'\s+', ' ', s).strip() + return s + + +def get_title_and_first_h2(path): + text = path.read_text(encoding='utf-8') + fm = FRONTMATTER_RE.match(text) + if not fm: + return None, None, None + title_match = TITLE_RE.search(fm.group(1)) + if not title_match: + return None, None, None + title = title_match.group(1).strip().strip('"').strip("'") + + body = text[fm.end():] + h2 = H2_RE.search(body) + if not h2: + return title, None, None + + # Detect if a later "## Introduction" exists (skipping the first H2 we found) + later_intro = False + for m in H2_RE.finditer(body): + if m.start() == h2.start(): + continue + if normalize(m.group(1)) == 'introduction': + later_intro = True + break + + return title, h2.group(1).strip(), later_intro + + +def main(): + root = Path('docs') if Path('docs').exists() else Path('.') + matches = [] + for md in sorted(root.rglob('*.md')): + if md.name == 'STYLE.md': + continue + title, h2, later_intro = get_title_and_first_h2(md) + if not title or not h2: + continue + n_title = normalize(title) + n_h2 = normalize(h2) + if n_title == n_h2 or n_title in n_h2 or n_h2 in n_title: + matches.append((md, title, h2, later_intro)) + + if not matches: + print("No duplicate-title H2s found.") + return 0 + + print(f"Found {len(matches)} candidate(s):\n") + for md, title, h2, later_intro in matches: + flag = " [HAS LATER ## Introduction — REVIEW]" if later_intro else "" + print(f" {md}") + print(f" title: {title!r}") + print(f" first H2: {h2!r}{flag}") + return 0 Review Comment: This script prints candidates but still exits with status 0 when matches are found. That makes it hard to use in automation/CI (it can't fail a job on findings) and is inconsistent with other audit scripts here that return non-zero on issues. Consider returning a non-zero exit code when `matches` is non-empty, or add a flag to control whether findings should fail the run. ########## docs/table-maintenance-service/optimizer-troubleshooting.md: ########## @@ -1,31 +1,31 @@ --- title: "Optimizer Troubleshooting" -slug: /table-maintenance-service/troubleshooting -keyword: table maintenance, optimizer, troubleshooting, spark, strategy -license: This software is licensed under the Apache License version 2. +slug: "/table-maintenance-service/troubleshooting" +keyword: "table maintenance, optimizer, troubleshooting, spark, strategy" +license: "This software is licensed under the Apache License version 2." --- ## `Invalid --type` Use kebab-case values such as `update-statistics`, not `update_statistics`. -## `--statistics-payload and --file-path cannot be used together` +## `--statistics-payload and --file-path Cannot Be Used together` For `local-stats-calculator`, use exactly one of them. -## `requires one of --statistics-payload or --file-path` +## `requires One of --statistics-payload or --file-path` When `--calculator-name local-stats-calculator` is used, one input source is required. -## `--partition-path must be a JSON array` +## `--partition-path Must Be a JSON array` Review Comment: This code-span heading changes casing inside backticks (`Must Be a JSON array`). If this is meant to match an exact validation error, the backticked content should stay verbatim (and consistent casing matters for copy/paste and for stable anchors). ########## scripts/intro_audit.py: ########## @@ -0,0 +1,89 @@ +#!/usr/bin/env python3 +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""Find Markdown files where body content appears before the first H2 heading.""" +import re +import sys +from pathlib import Path + +FRONTMATTER_RE = re.compile(r'^---\n(.*?)\n---\n', re.DOTALL) + + +def audit(path): + text = path.read_text(encoding='utf-8') + fm = FRONTMATTER_RE.match(text) + if not fm: + return None, None + body = text[fm.end():] + + body_lines = body.splitlines() + fm_line_count = fm.group(0).count('\n') + + in_html_comment = False + for i, line in enumerate(body_lines): + stripped = line.strip() + if not stripped: + continue + # Multi-line HTML comment (license header) + if in_html_comment: + if '-->' in stripped: + in_html_comment = False + continue + if stripped.startswith('<!--') and '-->' not in stripped: + in_html_comment = True + continue + if stripped.startswith('<!--') and stripped.endswith('-->'): + continue + # Single-line MDX import/export + if stripped.startswith('import ') or stripped.startswith('export '): + continue + if line.startswith('## ') and not line.startswith('### '): + return None, None # already starts with an H2, good + # Found a non-blank, non-boilerplate line that isn't an H2 + return fm_line_count + i + 1, line + + +def main(): + root = Path('docs') if Path('docs').exists() else Path('.') + matches = [] + for md in sorted(root.rglob('*.md')): + if md.name == 'STYLE.md': + continue + line_no, first_line = audit(md) + if line_no is None: + continue + matches.append((md, line_no, first_line)) + + if not matches: + print("All docs open with an H2 after frontmatter.") + return 0 + + print(f"Found {len(matches)} file(s) where body content precedes the first H2:\n") + for md, line_no, first_line in matches: + kind = "H1" if first_line.startswith('# ') and not first_line.startswith('## ') \ + else "H3" if first_line.startswith('### ') \ + else "H4+" if first_line.startswith('####') \ + else "prose" + preview = first_line[:80] + ('...' if len(first_line) > 80 else '') + print(f" {md}") + print(f" L{line_no} ({kind}): {preview}") + return 0 Review Comment: Like `title_h2_audit.py`, this script reports findings but exits with status 0 even when matches exist. If the intention is to use this as a pre-push/CI guardrail, consider returning non-zero when `matches` is non-empty (or add an explicit `--fail-on-match` flag) so it can be composed in automation. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
