docs: added more detailed setup instruction for linux #338
Conversation
…most markdown errors
WalkthroughDemoted several top-level headings to second-level and reflowed/cleaned prose across documentation; added a Troubleshooting header and explicit build/run steps in linux docs; inserted a changelog line. Added Markdown-linting CI jobs to Android, Linux, and Linux‑Rust workflows (docs/CI only). (50 words) Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (3)
🧰 Additional context used🪛 LanguageToolAAP Definitions.md[uncategorized] ~17-~17: Did you mean the proper noun “Apple Silicon”? (APPLE_PRODUCTS) [grammar] ~284-~284: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~287-~287: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~289-~289: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) README.md[style] ~57-~57: Consider using a more formal alternative. (MORE_HELP) [style] ~58-~58: To elevate your writing and sound more professional, you can use different wording here. (DIDNT_HAVE_THE_TIME) [grammar] ~93-~93: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) linux/README.md[grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) [grammar] ~159-~159: Ensure spelling is correct (QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1) 🔇 Additional comments (2)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
AAP Definitions.md (1)
17-18: Capitalize "Apple Silicon" per official terminology.Line 17 references "apple silicon devices" – this should be capitalized to "Apple Silicon" to align with Apple's official product terminology and improve consistency.
-Since apple likes to wall off some features behind specific OS versions, and apple silicon devices, some packets are -necessary to enable these features. +Since apple likes to wall off some features behind specific OS versions, and Apple Silicon devices, some packets are +necessary to enable these features.README.md (1)
57-58: Minor style improvements for professionalism.Lines 57–58 use conversational phrasing ("If you need more help" and "didn't have time") that could be more formal for professional documentation. Consider revising for a consistent, polished tone:
- Line 57: "If you need more help" → "For detailed setup instructions"
- Line 58: "maintainer didn't have time to work on it" → "limited feature support currently"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
AAP Definitions.md(11 hunks)CHANGELOG.md(1 hunks)README.md(6 hunks)linux/README.md(7 hunks)
🧰 Additional context used
🪛 LanguageTool
linux/README.md
[grammar] ~157-~157: Ensure spelling is correct
Context: ...providing the values for 8 frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ...ng the values for 8 frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) fo...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ...values for 8 frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ... for 8 frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ... frequencies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left and ri...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ...encies (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left and right ea...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ... (250Hz, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left and right ears. Th...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~157-~157: Ensure spelling is correct
Context: ...z, 500Hz, 1kHz, 2kHz, 3kHz, 4kHz, 6kHz, 8kHz) for both left and right ears. There ar...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
AAP Definitions.md
[uncategorized] ~17-~17: Did you mean the proper noun “Apple Silicon”?
Context: ...atures behind specific OS versions, and apple silicon devices, some packets are necessary to ...
(APPLE_PRODUCTS)
README.md
[style] ~57-~57: Consider using a more formal alternative.
Context: ...etup and starts LibrePods. If you need more help, check the [Linux README](/linux/README...
(MORE_HELP)
[style] ~58-~58: To elevate your writing and sound more professional, you can use different wording here.
Context: ...e many features, maintainer didn't have time to work on it) new version in developm...
(DIDNT_HAVE_THE_TIME)
[grammar] ~94-~94: Ensure spelling is correct
Context: ...igures out a fix. Until then, you must xposed. I used to provide a non-xposed method ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (6)
CHANGELOG.md (1)
1-3: Changelog link is well-placed.The added reference to the releases page provides helpful navigation for users seeking version history details.
linux/README.md (2)
76-99: Explicit build and run steps enhance clarity.Breaking out the directory creation (lines 76–83) and application execution (lines 93–99) as separate, clearly-labeled subsections makes the setup process easier to follow and reduces ambiguity for users unfamiliar with CMake workflows.
148-159: Hearing aid explanation is more readable.The reflow and line breaks in this section (lines 148–159) improve scannability and make it easier for users to understand the audiogram frequency range (250Hz–8kHz) and adjustment options without visual clutter.
AAP Definitions.md (1)
5-5: Heading hierarchy improvement.Converting section headings from single-hash (#) to double-hash (##) implies this document is now positioned as a subsection within a larger hierarchy. Ensure this aligns with the documentation structure and that cross-references and internal anchor links remain functional after this change.
Also applies to: 13-13, 33-33, 49-49
README.md (2)
24-27: Feature descriptions are clear and well-structured.The reflow of feature descriptions (including "Noise Control Modes") improves readability by breaking long lines without losing clarity or meaning.
102-109: VendorID and multi-device sections are well-documented.The reflow of VendorID configuration instructions (lines 102–103) and multi-device connectivity (lines 107–109) maintains clarity and procedural accuracy while improving line-break readability.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
README.md (2)
5-8: "Troubleshooting" label remains orphaned and should be a proper heading or removed.This issue was flagged in the previous review but remains unresolved. Line 5 contains a bare "Troubleshooting" label that breaks the document flow. Either convert it to a proper Markdown heading (e.g.,
## Troubleshooting) to mark a section, or remove it entirely so the product description flows naturally as the introduction.
94-96: Grammar issue in the Xposed requirement remains unresolved.This issue was flagged in the previous review. Line 94 reads "you must Xposed," which is grammatically incomplete. It should read "you must use Xposed" to clarify the requirement. Additionally, ensure consistent capitalization of "Xposed" throughout (currently mixed between "Xposed" and "xposed" on line 96).
Apply this diff:
-Until then, you must Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace -the bluetooth library with a locally patched one, but that was broken due to how various devices handled overlayfs -and a patched library. With xposed, you can also enable the DID hook enabling a few extra features. +Until then, you must use Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace +the bluetooth library with a locally patched one, but that was broken due to how various devices handled overlayfs +and a patched library. With Xposed, you can also enable the DID hook enabling a few extra features.
🧹 Nitpick comments (1)
README.md (1)
57-58: Optional: Elevate the tone for professionalism.Lines 57–58 read informally ("need more help," "didn't have time"). While functionally clear, the README could sound more professional by rephrasing:
Apply this diff:
-If you need more help, check the [Linux README](/linux/README.md), which provides a more detailed, -copy-and-paste-ready instruction. (doesn't have many features, maintainer didn't have time to work on it) +For detailed setup instructions, refer to the [Linux README](/linux/README.md), which provides copy-and-paste-ready steps. (Limited features; continued development pending.)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(6 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~57-~57: Consider using a more formal alternative.
Context: ...etup and starts LibrePods. If you need more help, check the [Linux README](/linux/README...
(MORE_HELP)
[style] ~58-~58: To elevate your writing and sound more professional, you can use different wording here.
Context: ...e many features, maintainer didn't have time to work on it) new version in developm...
(DIDNT_HAVE_THE_TIME)
[grammar] ~94-~94: Ensure spelling is correct
Context: ...igures out a fix. Until then, you must Xposed. I used to provide a non-Xposed method ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
fixed because of an error from coderabbitai
jaunger-app
force-pushed
the
jaunger/docs
branch
from
e49ea18 to
e4a1444
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
README.md (1)
94-96: Fix grammatical error in Xposed requirement.Line 94 contains the incomplete phrase "you must Xposed," which is grammatically incorrect. It should be "you must use Xposed" or "you must have Xposed" to clearly convey the requirement.
Apply this diff to fix the grammar:
-Until then, you must Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace +Until then, you must use Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace
🧹 Nitpick comments (1)
README.md (1)
57-58: Improve the tone and formality of the Linux instructions note.The phrasing "If you need more help" and "maintainer didn't have time" uses informal language that reduces the professionalism of the documentation. Use more formal alternatives to maintain a consistent tone.
Apply this diff to improve formality:
-If you need more help, check the [Linux README](/linux/README.md), which provides a more detailed, -copy-and-paste-ready instruction. (doesn't have many features, maintainer didn't have time to work on it) +For detailed, step-by-step instructions and copy-paste-ready commands, refer to the [Linux README](/linux/README.md). +(Note: The Linux version is under active development and does not yet include all features.)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(6 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~57-~57: Consider using a more formal alternative.
Context: ...etup and starts LibrePods. If you need more help, check the [Linux README](/linux/README...
(MORE_HELP)
[style] ~58-~58: To elevate your writing and sound more professional, you can use different wording here.
Context: ...e many features, maintainer didn't have time to work on it) new version in developm...
(DIDNT_HAVE_THE_TIME)
[grammar] ~94-~94: Ensure spelling is correct
Context: ...igures out a fix. Until then, you must Xposed. I used to provide a non-Xposed method ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (3)
README.md (3)
19-20: Editorial improvement to paragraph flow.The rewording enhances clarity and readability of the device compatibility section without altering the technical information.
48-56: Well-structured Linux installation instructions.The new step-by-step instructions are clear and logically organized, providing users with the essential build process (clone → create build folder → CMake → compile → run). The reference to linux/README.md appropriately bridges to more detailed documentation without overwhelming the main README.
102-103: Editorial improvements throughout the document.The remaining changes apply consistent rewording and reformatting for improved clarity and readability across the VendorID, multi-device connectivity, accessibility settings, notes sections, and trademark notice. These editorial changes maintain the original technical information while enhancing document flow.
Also applies to: 107-109, 113-118, 122-131, 139-145, 148-153, 183-184
also removed merge conflicts
jaunger-app
force-pushed
the
jaunger/docs
branch
from
248c76a to
b02de7f
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
README.md (2)
5-5: Remove the orphaned "Troubleshooting" text or format it as a proper Markdown heading.Line 5 contains "Troubleshooting" as plain text that disrupts the introduction flow. This was flagged in a previous review. Either remove this line entirely if it's a leftover artifact, or convert it to a Markdown heading (e.g.,
## Troubleshooting) and add corresponding content below. Currently, it reads as an unintended fragment before the "What is LibrePods?" introduction.
94-96: Fix the unresolved grammar error in line 94.Line 94 reads "you must Xposed" which is grammatically incomplete. This issue was flagged in a previous review and remains unresolved. The sentence should read "you must use Xposed" to be grammatically correct and clear.
Apply this diff:
-Until then, you must Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace +Until then, you must use Xposed. I used to provide a non-Xposed method too, where the module used overlayfs to replace
🧹 Nitpick comments (1)
README.md (1)
57-58: Elevate the formality and professionalism of the closing remarks.Lines 57–58 use informal phrasing ("If you need more help" and "maintainer didn't have time") that could be more professional in a README. Consider revising to be more formal and focused on the actual status/limitations rather than the personal situation.
Suggested revision:
-If you need more help, check the [Linux README](./linux/README.md), which provides a more detailed, -copy-and-paste-ready instruction. (doesn't have many features, maintainer didn't have time to work on it) +For detailed instructions, refer to the [Linux README](./linux/README.md), which provides +step-by-step guidance. (Note: Feature parity with Android is currently limited.)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.github/workflows/ci-android.yml(1 hunks).github/workflows/ci-linux-rust.yml(1 hunks).github/workflows/ci-linux.yml(1 hunks)README.md(6 hunks)
🧰 Additional context used
🪛 actionlint (1.7.9)
.github/workflows/ci-linux-rust.yml
19-19: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
.github/workflows/ci-android.yml
27-27: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
.github/workflows/ci-linux.yml
14-14: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
🪛 LanguageTool
README.md
[style] ~57-~57: Consider using a more formal alternative.
Context: ...etup and starts LibrePods. If you need more help, check the [Linux README](./linux/READM...
(MORE_HELP)
[style] ~58-~58: To elevate your writing and sound more professional, you can use different wording here.
Context: ...e many features, maintainer didn't have time to work on it) new version in developm...
(DIDNT_HAVE_THE_TIME)
[grammar] ~94-~94: Ensure spelling is correct
Context: ...igures out a fix. Until then, you must Xposed. I used to provide a non-Xposed method ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (8)
README.md (5)
6-8: LGTM.The introduction paragraph is well-structured and clearly communicates the core value proposition. The reflow improves readability.
19-20: LGTM.The note is clearly written and the reflow improves readability without changing meaning.
24-32: LGTM.The feature list reflow improves readability while preserving structure and clarity. The asterisk notation correctly links to the explanation on line 40.
46-56: LGTM.The Linux installation instructions are clear, step-by-step, and guide users through the complete workflow. The previous grammar issue ("How are you install") is now resolved to the correct phrasing "How to install LibrePods on Linux?"
102-103: LGTM.The editorial and formatting changes throughout these sections improve readability and professionalism. Paragraph reflows, capitalization consistency (e.g., "Xposed" capitalized), and punctuation adjustments are all well-executed. The supporter and acknowledgments lists are cleanly formatted.
Also applies to: 107-109, 113-118, 122-131, 139-152, 183-184
.github/workflows/ci-android.yml (1)
27-27: Align linting job to useactions/checkout@v4matching the build job.The linting job uses
actions/checkout@v3while the build-debug-apk job in the same workflow uses@v4(line 36). This version inconsistency conflicts with actionlint's recommendation to use the newer version. Align both to@v4for security and consistency.Also, verify whether
continue-on-error: true(line 30) is intentional—if markdown linting failures should fail the build, remove this setting.Apply this diff to update the action version:
- name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: use DavidAnson/markdownlint-action uses: DavidAnson/markdownlint-cli2-action@v21 continue-on-error: true with: globs: '**/*.md'.github/workflows/ci-linux-rust.yml (1)
19-19: Align linting job to useactions/checkout@v4matching the build job.The linting job uses
actions/checkout@v3while the build job in the same workflow uses@v4. Update to@v4for consistency across the workflow.Also verify whether
continue-on-error: true(line 22) is intentional—if markdown linting failures should fail the build, remove this setting..github/workflows/ci-linux.yml (1)
14-14: Updateactions/checkout@v3to@v4for security and to address Node.js 16 deprecation.The current checkout action uses v3, which runs on the deprecated Node.js 16 runtime and triggers deprecation warnings. v4 is the currently maintained version with updated Node runtime and improved security. Upgrade to v4 to align with current GitHub Actions best practices and avoid future breaking changes.
Additionally, verify whether
continue-on-error: trueis intentional—if markdown linting failures should fail the build, remove this setting.
2 participants
This PR improves overall documentation quality by addressing several Markdown issues and enhancing the clarity of the installation instructions.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.