Skip to content

docs: Add submodule initialization instructions to README #172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jackluo923 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Add submodule initialization instructions to README #172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d0ff14e
docs: Add submodule initialization instructions to README
jackluo923 Oct 31, 2025
61ab551
ci: Add build workflow for documentation-only changes
jackluo923 Oct 31, 2025
bb3dce5
chore: Add comment about submodule initialization to CMakeLists.txt
jackluo923 Oct 31, 2025
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
24 changes: 24 additions & 0 deletions .github/workflows/build-docs-only.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: "build"
Copy link

@coderabbitai coderabbitai bot Oct 31, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Workflow name collision risk with concurrency group.

The workflow is named "build" (line 1), but concurrency group uses ${{github.workflow}} (line 16). If another "build" workflow exists in the repository, both will share the same concurrency group, potentially causing the docs-only workflow to cancel in-progress actual builds or vice versa.

Rename this workflow to something distinct, e.g., "docs-only-check" or "build-docs-only", to ensure independent concurrency handling.

Apply this diff to fix the workflow name:

-name: "build"
+name: "build-docs-only"

Also applies to: 15-17

🤖 Prompt for AI Agents 
.github/workflows/build-docs-only.yaml lines 1 and 15-17: the workflow is named
"build" which collides with other workflows when the concurrency group uses `${{
github.workflow }}`; rename the workflow to a unique name like "build-docs-only"
(or "docs-only-check") by changing the name value on line 1 and keep the
existing concurrency group unchanged so it will resolve to the new unique name,
ensuring this workflow no longer shares a concurrency group with other "build"
workflows.


on:
pull_request:
paths:
- "README.md"
- "docs/**/*"
- "*.md"
push:
paths:
- "README.md"
- "docs/**/*"
- "*.md"

concurrency:
group: "${{github.workflow}}-${{github.ref}}"
cancel-in-progress: true

jobs:
build:
runs-on: ubuntu-latest

Check failure on line 21 in .github/workflows/build-docs-only.yaml

View workflow job for this annotation

GitHub Actions / lint (ubuntu-24.04) 

21:14 [quoted-strings] string value is not quoted with double quotes
steps:
- name: "Documentation-only changes"
run: echo "Only documentation changed, skipping build"

Check failure on line 24 in .github/workflows/build-docs-only.yaml

View workflow job for this annotation

GitHub Actions / lint (ubuntu-24.04) 

24:14 [quoted-strings] string value is not quoted with double quotes
Comment on lines +20 to +24
Copy link

@coderabbitai coderabbitai bot Oct 31, 2025

Choose a reason for hiding this comment

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

🧹 Nitpick | 🔵 Trivial

Minimal informational workflow is acceptable.

The job simply echoes a message indicating that only documentation changed and the build is skipped. This satisfies the requirement of having at least one job in the workflow (GitHub Actions requires this). The informational step serves as a clear signal in CI logs.

Consider whether more comprehensive documentation checks (e.g., link validation, Markdown linting) should be added in the future, but the current approach is acceptable as a foundation.

🤖 Prompt for AI Agents 
.github/workflows/build-docs-only.yaml lines 20-24: The workflow currently
contains a single informational job that echoes a message when only
documentation changes are detected; leave this minimal job as-is to satisfy
GitHub Actions requirement, or if desired add future steps for doc-quality
checks (e.g., markdownlint, link checker) by inserting additional steps under
the job to run those tools and fail on errors.

1 change: 1 addition & 0 deletions CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
cmake_minimum_required(VERSION 3.22.1)

# Ensure submodules are initialized before building
Copy link

@coderabbitai coderabbitai bot Oct 31, 2025

Choose a reason for hiding this comment

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

🧹 Nitpick | 🔵 Trivial

Consider adding CMake verification logic alongside the comment.

While the comment provides helpful guidance, it is non-functional and will not prevent build failures when submodules are missing. Users who encounter initialization errors may not read this comment until after the build fails.

A more robust approach would add CMake logic to detect uninitialized submodules early and emit a clear, actionable error message pointing users to the README or documentation.

Consider adding a check similar to the following before or after the project() call:

# Check if the submodule is initialized
if(NOT EXISTS "${CMAKE_SOURCE_DIR}/build/deps/yscope-dev-utils/CMakeLists.txt")
    message(FATAL_ERROR
        "Git submodule 'yscope-dev-utils' is not initialized. "
        "Please run: git submodule update --init --recursive"
    )
endif()

This ensures that:

  • The error is caught early during CMake configuration
  • The error message provides the exact command users need to run
  • The build fails immediately with clear guidance instead of failing later with cryptic errors
🤖 Prompt for AI Agents 
In CMakeLists.txt around line 3, the comment warns about uninitialized git
submodules but provides no enforcement; add a CMake configuration-time check
that verifies the expected submodule path exists and, if missing, emits a clear
fatal error instructing users to run the proper git submodule update --init
--recursive command (or pointing to README) so configuration fails early with an
actionable message.

project(
log_surgeon
VERSION 0.0.1
Expand Down
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,12 @@ Requirements:
* [Task] >= 3.38
* [uv] >= 0.7.10

After cloning the repository, initialize submodules:

```shell
git submodule update --init --recursive
```

To build and install the project to `$HOME/.local`:

```shell
Expand Down
Loading