docs: Add quick-start guide. #36
Conversation
WalkthroughThe pull request introduces a new documentation file Changes
Sequence DiagramsequenceDiagram
participant User as User
participant Task as Task Function
participant Client as Spider Client
participant Cluster as Spider Cluster
User->>Task: Implement task function
User->>Task: Build shared library
User->>Client: Write client application
Client->>Cluster: Connect to cluster
Client->>Cluster: Submit task
Cluster->>Task: Execute task
Task-->>Cluster: Return result
Cluster-->>Client: Provide result
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (5)
docs/quick-start.md (5)
21-25: Consider enhancing the requirements sectionA few suggestions to improve clarity:
- Add minimum version requirements for CMake
- Consider adding approximate disk space requirements for Docker images
- Format the Docker link reference to be consistent with the text (i.e., use
[Docker]in line 23)
71-71: Replace hard tab with spacesThe line contains a hard tab character. For consistency, use spaces for indentation.
- return x + y; + return x + y;🧰 Tools
🪛 Markdownlint (0.37.0)
71-71: Column: 1
Hard tabs(MD010, no-hard-tabs)
29-34: Consider expanding on TaskContext usageWhile the note mentions that TaskContext will be explained later, it would be helpful to provide a brief description of its purpose here, as it's a required parameter for all tasks.
254-266: Add execution verification stepsConsider adding:
- Expected output for successful execution
- Common error messages and their resolution
- How to verify the task was executed on the cluster
267-271: Enhance the next steps sectionConsider adding:
- Links to advanced topics (even if the pages don't exist yet)
- Brief overview of what fault tolerance means in Spider
- Examples of more complex tasks users might want to try
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/quick-start.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/quick-start.md
[uncategorized] ~165-~165: Possible missing comma found.
Context: ...ent can be compiled like any normal C++ application except that we need to link it to the S...
(AI_HYDRA_LEO_MISSING_COMMA)
🪛 Markdownlint (0.37.0)
docs/quick-start.md
71-71: Column: 1
Hard tabs
(MD010, no-hard-tabs)
46-46: null
Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
62-62: null
Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
101-101: null
Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/quick-start.md
Outdated
| # Building the task into a shared library | ||
|
|
||
| In order for Spider to run a task, the task needs to be compiled into a shared library that Spider | ||
| can load. | ||
|
|
||
| TODO: Instructions and an example showing how to compile tasks into a shared library. | ||
|
|
There was a problem hiding this comment.
Critical: Add missing build instructions
The TODO marker indicates missing instructions for compiling tasks into a shared library. This is a blocking issue as users cannot proceed without these instructions. Consider adding:
- CMake configuration examples
- Compiler flags for shared library creation
- Output location expectations
Would you like me to help draft the missing build instructions section?
| switch (job_status) { | ||
| case JobStatus::Succeeded: { | ||
| auto result = job_status.get_result(); | ||
| if (result == job_status.get_result()) { |
There was a problem hiding this comment.
Fix the result comparison logic
The condition is comparing the result with itself, which will always be true:
if (result == job_status.get_result())Should be:
-if (result == job_status.get_result())
+if (result == 5) // Expected sum of 2 + 3
docs/quick-start.md
Outdated
| # Building the client | ||
|
|
||
| The client can be compiled like any normal C++ application except that we need to link it to the | ||
| Spider client library. | ||
|
|
||
| TODO: Instructions and an example for how to compile the client application. | ||
|
|
There was a problem hiding this comment.
Critical: Add missing client build instructions
The TODO marker indicates missing instructions for compiling the client application. This is a blocking issue as users cannot proceed without these instructions. Consider adding:
- CMake configuration examples
- Required Spider library linking flags
- Build system requirements
Would you like me to help draft the missing client build instructions section?
🧰 Tools
🪛 LanguageTool
[uncategorized] ~165-~165: Possible missing comma found.
Context: ...ent can be compiled like any normal C++ application except that we need to link it to the S...
(AI_HYDRA_LEO_MISSING_COMMA)
| --env MARIADB_USER=spider \ | ||
| --env MARIADB_PASSWORD=password \ | ||
| --env MARIADB_DATABASE=spider-storage \ | ||
| --env MARIADB_ALLOW_EMPTY_ROOT_PASSWORD=true \ | ||
| --publish 3306:3306 mariadb:latest |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add security warning for credentials
The example uses hardcoded credentials in plain text. Consider adding a security note about:
- Using environment variables for credentials
- Implementing proper authentication in production
- Using secure password practices
| To start the scheduler, run: | ||
|
|
||
| ```shell | ||
| build/src/spider/spider_schdeuler \ |
There was a problem hiding this comment.
Fix typo in scheduler command
There's a typo in the executable name.
-build/src/spider/spider_schdeuler \
+build/src/spider/spider_scheduler \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| build/src/spider/spider_schdeuler \ | |
| build/src/spider/spider_scheduler \ |
| std::cerr << "`sum` returned unexpected result. Expected: 5. Actual: " << result | ||
| << '\n'. | ||
| return 1; |
There was a problem hiding this comment.
Fix syntax error in error message
There's an invalid period after the string concatenation.
- << '\n'.
+ << '\n';📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| std::cerr << "`sum` returned unexpected result. Expected: 5. Actual: " << result | |
| << '\n'. | |
| return 1; | |
| std::cerr << "`sum` returned unexpected result. Expected: 5. Actual: " << result | |
| << '\n'; | |
| return 1; |
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (4)
docs/quick-start.md (4)
157-157:⚠️ Potential issueFix the result comparison logic
The condition is comparing the result with itself, which will always be true.
-if (result == job_status.get_result()) +if (result == 5) // Expected sum of 2 + 3
160-162:⚠️ Potential issueFix syntax error in error message
There's an invalid period after the string concatenation.
- << '\n'. + << '\n';
231-235:⚠️ Potential issueAdd security warning for credentials
The example uses hardcoded credentials in plain text. Consider adding a security note about:
- Using environment variables for credentials
- Implementing proper authentication in production
- Using secure password practices
257-257:⚠️ Potential issueFix typo in scheduler command
There's a typo in the executable name.
-build/src/spider/spider_schdeuler \ +build/src/spider/spider_scheduler \
🧹 Nitpick comments (4)
docs/quick-start.md (4)
29-29: Fix grammatical errorAdd the missing article "a":
-In Spider, a task is C++ function that satisfies the following conditions: +In Spider, a task is a C++ function that satisfies the following conditions:🧰 Tools
🪛 LanguageTool
[uncategorized] ~29-~29: Possible missing article found.
Context: ... # Writing a task In Spider, a task is C++ function that satisfies the following...(AI_HYDRA_LEO_MISSING_A)
71-71: Replace hard tabs with spacesReplace the hard tab with spaces to maintain consistent formatting throughout the document.
🧰 Tools
🪛 Markdownlint (0.37.0)
71-71: Column: 1
Hard tabs(MD010, no-hard-tabs)
46-122: Use proper heading structure for file namesInstead of using emphasis (_) for file names, consider using a proper heading structure:
-_tasks.hpp_ +### tasks.hpp -_tasks.cpp_ +### tasks.cpp -_client.cpp_ +### client.cpp🧰 Tools
🪛 Markdownlint (0.37.0)
71-71: Column: 1
Hard tabs(MD010, no-hard-tabs)
46-46: null
Emphasis used instead of a heading(MD036, no-emphasis-as-heading)
62-62: null
Emphasis used instead of a heading(MD036, no-emphasis-as-heading)
122-122: null
Emphasis used instead of a heading(MD036, no-emphasis-as-heading)
186-186: Add missing commas for better readabilityAdd commas in the following sentences:
-The client can be compiled like any normal C++ application except that we need to link it to the Spider client library. +The client can be compiled like any normal C++ application, except that we need to link it to the Spider client library. -In future guides, we'll explain how to write more complex tasks as well as how to leverage Spider's support for fault tolerance. +In future guides, we'll explain how to write more complex tasks, as well as how to leverage Spider's support for fault tolerance.Also applies to: 311-311
🧰 Tools
🪛 LanguageTool
[uncategorized] ~186-~186: Possible missing comma found.
Context: ...ent can be compiled like any normal C++ application except that we need to link it to the S...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/quick-start.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/quick-start.md
[uncategorized] ~29-~29: Possible missing article found.
Context: ... # Writing a task In Spider, a task is C++ function that satisfies the following...
(AI_HYDRA_LEO_MISSING_A)
[uncategorized] ~186-~186: Possible missing comma found.
Context: ...ent can be compiled like any normal C++ application except that we need to link it to the S...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~311-~311: Possible missing comma found.
Context: ...we'll explain how to write more complex tasks as well as how to leverage Spider's sup...
(AI_HYDRA_LEO_MISSING_COMMA)
🪛 Markdownlint (0.37.0)
docs/quick-start.md
71-71: Column: 1
Hard tabs
(MD010, no-hard-tabs)
46-46: null
Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
62-62: null
Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
122-122: null
Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
Description
This PR adds a quick-start guide for writing a basic task and running it on Spider. In future PRs, we will explain how to write complex tasks (e.g., tasks joined together into task graph) as well as how to use Spider's data and key-value stores.
NOTE: This should not be merged until the scheduler and worker can be run as standalone processes.
Validation performed
Summary by CodeRabbit
Summary by CodeRabbit