Skip to content

docs: refresh READMEs and scope CI triggers by language - #1111

Merged
ColinLeeo merged 3 commits into
apache:developfrom
ColinLeeo:colin/docs-and-ci-path-filters
Nov 16, 2026
Merged

ColinLeeo merged 3 commits into
apache:developfrom
ColinLeeo:colin/docs-and-ci-path-filters

Conversation

@ColinLeeo

Copy link
Copy Markdown
Contributor

What changed

Documentation

  • Java: update the dependency version to 2.5.0, fix TSRecord argument order, the DataPoint.getDataPoint value type, the Path constructor, writeRecord, and the reader variable; rewrite java/examples/readme.md around the actual example classes.
  • C++: use the common:: namespace for the parallel-write switches, replace the removed set_write_thread_count with set_thread_count, correct the default pool description, and fix the Chinese build instructions and output paths.
  • Python: point at examples/example.py and the real public API modules.
  • Root README: align the tsfile-cli command table and output formats with the implementation, and align the encoding table and reference links (TEXT -> PLAIN, add DATE/TIMESTAMP/STRING/BLOB) with the current IoTDB documentation.

CI

  • Replace broad paths-ignore filters with per-language paths whitelists, excluding Markdown and unrelated language directories.
  • Keep shared build inputs (pom.xml, mvnw, mvnw.cmd, .mvn/**, checkstyle.xml, and compat/compatibility-matrix.csv) in the workflows that consume them.
  • Build the native library with -Dbuild.test=OFF in the Go and CodeQL workflows, which do not run C++ unit tests.
  • Document the path-filter maintenance rule in CLAUDE.md.

Why

Documentation-only changes and changes to another language currently start C++/Java/Python test matrices. With these filters, a README-only PR matches no test workflow.

Validation

  • git diff --check
  • all modified workflow YAML parses
  • path-filter scenario assertions: README-only triggers 0 workflows; each language triggers only its workflows; compat/compatibility-matrix.csv triggers the Java/C++ suites, coverage, and the compatibility matrix
  • the full Maven suite was not run because no source, POM, or build script changed

Reviewer notes

  • This PR modifies workflow files, so it still triggers CI once; after merge, documentation-only PRs will not.
  • CodeQL remains a single four-language matrix: any language source change still runs all four analyses.
  • The Python workflows intentionally keep running the C++ unit tests, because -P with-python includes the cpp module and verify reaches the CTest phase.

Fix outdated Java API snippets (TSRecord, DataPoint, Path, writeRecord),
the released dependency version, and the example class list. Align the C++
parallel-write API names and Chinese build instructions, and point the
Python README at the real example and API modules. Update the CLI command
table and encoding matrix to match current behavior and the current IoTDB
reference documentation.
Replace broad paths-ignore filters with per-language path whitelists so
documentation-only changes and unrelated language directories do not start
builds. Keep shared build inputs (pom.xml, mvnw, .mvn, checkstyle.xml, and
the compatibility matrix) in the workflows that consume them, and document
the maintenance rule in CLAUDE.md.

Build the native library without C++ test targets in the Go and CodeQL
workflows, which do not run C++ unit tests.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The CodeQL path allowlists omit packaging/** for pushes and pull requests, causing packaging-only Python changes to skip per-change security analysis.

1 open issue
What changed in this PR

This PR refreshes TsFile’s documentation to match current APIs and CLI behavior, and narrows CI triggers to reduce builds for documentation-only and unrelated-language changes.

Changes:

  • Correct English and Chinese SDK instructions, Java examples, and CLI documentation.
  • Scope workflow path filters by language and shared build inputs.
  • Disable native test builds for Go-related jobs and document path-filter maintenance.
File Description
README.md Refresh encoding recommendations and CLI reference.
README-zh.md Align Chinese encoding and CLI documentation.
python/​README.md Correct public API and example paths.
python/​README-zh.md Correct Chinese API and example references.
java/​tsfile/​README.md Update dependency version and API snippets.
java/​tsfile/​README-zh.md Fix Chinese dependency and API examples.
java/​examples/​readme.md Describe current writer and reader examples.
cpp/​README.md Correct threading API namespaces.
cpp/​README-zh.md Update build instructions and threading guidance.
CLAUDE.md Document CI path-filter maintenance.
.github/​workflows/​unit-test-python.yml Scope triggers to Python, C++, and build inputs.
.github/​workflows/​unit-test-python-msvc.yml Apply scoped triggers to Windows Python tests.
.github/​workflows/​unit-test-java.yml Scope triggers to Java and shared inputs.
.github/​workflows/​unit-test-go.yml Exclude Markdown and disable native test builds.
.github/​workflows/​unit-test-cpp.yml Scope triggers to C++ and shared inputs.
.github/​workflows/​unit-test-cpp-msvc.yml Apply scoped triggers to Windows C++ tests.
.github/​workflows/​cppcheck.yml Narrow triggers to relevant native analysis inputs.
.github/​workflows/​cpp-dependency-source.yml Exclude Markdown and C++ documentation.
.github/​workflows/​compatibility-test.yml Exclude Markdown from compatibility triggers.
.github/​workflows/​codeql.yml Add path filters and streamline Go’s native build.
.github/​workflows/​code-coverage.yml Scope coverage triggers to Java, C++, and shared inputs.

Review effort: Balanced

Comment thread .github/workflows/codeql.yml Resolved
Packaging scripts and tests are Python sources analyzed by CodeQL. Add
packaging/** to the push and pull-request allowlists while retaining the
Markdown exclusion.
@ColinLeeo
ColinLeeo merged commit b224eba into apache:develop Nov 16, 2026
53 of 54 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants