More docs updates#34
Conversation
And fix a few typos in the process!
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Summary of ChangesHello @josh-padnick, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the quality and user experience of the Runbooks documentation. By integrating "cspell", it establishes a robust spell-checking mechanism to maintain high editorial standards. The UI tour has been upgraded from static images to an engaging video, providing a clearer demonstration of the product. Furthermore, improvements to the Lambda test script offer more actionable feedback for developers, while various textual refinements across the documentation ensure greater clarity and consistency. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces several documentation updates, including the addition of a spell checker (cspell), fixing numerous typos, and improving heading consistency. A notable change is the replacement of the UI tour page with an embedded video, which modernizes the content. Furthermore, a shell script in the test data has been enhanced to provide more detailed error feedback for Lambda function invocations. Overall, these are positive changes that improve the quality and usability of the documentation. I've included a couple of suggestions to further enhance the robustness of a script and to improve consistency in one of the documentation files.
| # Check if the response contains a Lambda runtime error | ||
| RESPONSE=$(cat "$RESPONSE_FILE") | ||
| if echo "$RESPONSE" | grep -q '"errorType"'; then | ||
| echo "❌ Lambda function returned an error!" | ||
| echo "" | ||
| echo "📄 Response:" | ||
| echo "$RESPONSE" | ||
| echo "" | ||
|
|
||
| # Extract error details if possible | ||
| ERROR_TYPE=$(echo "$RESPONSE" | grep -o '"errorType":"[^"]*"' | cut -d'"' -f4) | ||
| ERROR_MESSAGE=$(echo "$RESPONSE" | grep -o '"errorMessage":"[^"]*"' | cut -d'"' -f4) | ||
|
|
||
| if [ -n "$ERROR_TYPE" ]; then | ||
| echo " Error Type: $ERROR_TYPE" | ||
| fi | ||
| if [ -n "$ERROR_MESSAGE" ]; then | ||
| echo " Error Message: $ERROR_MESSAGE" | ||
| fi | ||
| echo "" | ||
| echo " Possible causes:" | ||
| echo " - Missing dependencies (check your package/deployment)" | ||
| echo " - Handler configuration is incorrect" | ||
| echo " - Runtime error in your Lambda code" | ||
| exit 1 | ||
| fi | ||
|
|
||
| echo "✅ Lambda function invoked successfully!" | ||
| echo "" | ||
| echo "📄 Response:" | ||
| cat "$RESPONSE_FILE" | ||
| echo "$RESPONSE" | ||
| echo "" | ||
| exit 0 |
There was a problem hiding this comment.
This is a great improvement for error handling! To make it even more robust and user-friendly, I have a few suggestions:
- Robust JSON Parsing: Using
grepandcutto parse JSON is brittle and can fail if the error message contains special characters like escaped quotes. Using a dedicated JSON parser likejqis much more reliable. - Pretty-Print JSON: For better readability, the JSON response can be pretty-printed if
jqis available. This is helpful for both error and success cases.
Here's a suggestion that implements these ideas, using jq if present and falling back to the current method otherwise.
# Check if the response contains a Lambda runtime error
RESPONSE=$(cat "$RESPONSE_FILE")
if echo "$RESPONSE" | grep -q '"errorType"'; then
echo "❌ Lambda function returned an error!"
echo ""
echo "📄 Response:"
echo "$RESPONSE" | (command -v jq >/dev/null && jq . || cat)
echo ""
# Extract error details if possible
if command -v jq >/dev/null; then
ERROR_TYPE=$(echo "$RESPONSE" | jq -r '.errorType // ""')
ERROR_MESSAGE=$(echo "$RESPONSE" | jq -r '.errorMessage // ""')
else
# Fallback for when jq is not installed. Note: this can be brittle.
ERROR_TYPE=$(echo "$RESPONSE" | grep -o '"errorType":"[^"]*"' | cut -d'"' -f4)
ERROR_MESSAGE=$(echo "$RESPONSE" | grep -o '"errorMessage":"[^"]*"' | cut -d'"' -f4)
fi
if [ -n "$ERROR_TYPE" ]; then
echo " Error Type: $ERROR_TYPE"
fi
if [ -n "$ERROR_MESSAGE" ]; then
echo " Error Message: $ERROR_MESSAGE"
fi
echo ""
echo " Possible causes:"
echo " - Missing dependencies (check your package/deployment)"
echo " - Handler configuration is incorrect"
echo " - Runtime error in your Lambda code"
exit 1
fi
echo "✅ Lambda function invoked successfully!"
echo ""
echo "📄 Response:"
echo "$RESPONSE" | (command -v jq >/dev/null && jq . || cat)
echo ""
exit 0
|
/gemini Can you do a fresh review of all content? |
There was a problem hiding this comment.
Code Review
This pull request introduces a significant overhaul of the documentation, greatly improving its structure, clarity, and content. The addition of new pages for core concepts like boilerplate, variables, and runbook-structure provides a much better learning path for authors. The refactoring of the block component documentation, including adding comparison tables, is particularly helpful. I've found a few minor issues, mostly typos and small inconsistencies in the new documentation, which I've detailed in the comments.
| ## Security concerns | ||
|
|
||
| Runbooks are designed to streamline the code generation and commands you might otherwise run on your local computer. This has important security implications you should be aware of prior to running Runbooks. | ||
| Runbooks is designed to streamline the code generation and commands you might otherwise run on your local computer. This has important security implications you should be aware of prior to running Runbooks. |
There was a problem hiding this comment.
There's a subject-verb agreement inconsistency. On line 13, you use "Runbooks are...", but here you use "Runbooks is...". For consistency, it's best to use the plural form throughout.
| Runbooks is designed to streamline the code generation and commands you might otherwise run on your local computer. This has important security implications you should be aware of prior to running Runbooks. | |
| Runbooks are designed to streamline the code generation and commands you might otherwise run on your local computer. This has important security implications you should be aware of prior to running Runbooks. |
| <path d="M12 2L3 7v10l9 5 9-5V7l-9-5zm0 2.18l6.26 3.48L12 11.14 5.74 7.66 12 4.18zm-7 5.04l6 3.33v6.63l-6-3.33v-6.63zm8 9.96v-6.63l6-3.33v6.63l-6 3.33z" fill="currentColor"/> | ||
| `; | ||
|
|
||
| function replaceTerrformIconsWithOpenTofu() { |
There was a problem hiding this comment.
There's a typo in the function name: Terrform should be Terraform. Remember to update the call sites on lines 38, 40, and 44 as well.
function replaceTerraformIconsWithOpenTofu() {
| - `allowPermanentHide` (boolean) - When true with confirmationText, adds "Don't show again" option | ||
| - `storageKey` (string) - Unique key for localStorage (required with allowPermanentHide) | ||
| - `className` (string) - Additional CSS classes | ||
| - `storageKey` (string) - Unique key for localStorage (required with allowPermanentHide |
There was a problem hiding this comment.
There's a missing closing parenthesis in the description for the storageKey prop.
| - `storageKey` (string) - Unique key for localStorage (required with allowPermanentHide | |
| - `storageKey` (string) - Unique key for localStorage (required with allowPermanentHide) |
|
|
||
| ### Using inputsId | ||
|
|
||
| The Check command or script ulls its values from a separate Inputs block. |
There was a problem hiding this comment.
There's a typo here. "ulls" should be "pulls".
| The Check command or script ulls its values from a separate Inputs block. | |
| The Check command or script pulls its values from a separate Inputs block. |
| command="cd generated && terraform apply -auto-approve" | ||
| title="Deploy VPC" | ||
| successMessage="VPC deployed!" | ||
| /> |
There was a problem hiding this comment.
This line appears to be a stray /> from a copy-paste error and should be removed.
| 2. **Non-interactive mode:** Variables can also be set non-interactively, via command-line options, so that Boilerplate can be used in automated settings (e.g. during automated tests). | ||
| 3. **Flexible templating:** Boilerplate uses Go Template for templating, which gives you the ability to do formatting, conditionals, loops, and call out to Go functions. It also includes helpers for common tasks such as loading the contents of another file, executing a shell command and rendering the output in a template, and including partial templates. | ||
| 4. **Dependencies.** You can "chain" templates together, conditionally including other templates depending on variable values. | ||
| 4. **Variable types:** Boilerplate variables support types, so you have first-class support for strings, ints, bools, lists, maps, and enums. |
There was a problem hiding this comment.
This numbered list has a duplicate number. This item should be 5. instead of 4.. Please also update the subsequent numbers in the list accordingly.
| 4. **Variable types:** Boilerplate variables support types, so you have first-class support for strings, ints, bools, lists, maps, and enums. | |
| 5. **Variable types:** Boilerplate variables support types, so you have first-class support for strings, ints, bools, lists, maps, and enums. |
| <Aside type="caution"> | ||
| When you update a `command` property, local template, or local script, the runbook will automatically load these changes in the _UI_, but because of the [executable registry](/security/execution-model/#executable-registry), the runbook will continue to execute the _old_ versions of these files. The solution is to always restart your runbook (re-run `runbooks watch`) when you make a template or script change. | ||
| </Aside> |
There was a problem hiding this comment.
This warning is a duplicate of the one on lines 13-15. It should be removed to avoid redundancy.
1 participant
No description provided.