docs: add app- and package-level READMEs with root index#221
Open
snowfox1003 wants to merge 7 commits into
Open
docs: add app- and package-level READMEs with root index#221snowfox1003 wants to merge 7 commits into
snowfox1003 wants to merge 7 commits into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds or updates README files across the repo: root README now lists critical environment variables and an app-level README index; ChangesPackage and App Documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 3
🧹 Nitpick comments (2)
scripts/README.md (1)
8-8: ⚡ Quick winEnhance usage guidance for
list_cross_app_imports.py.The
clean-macos.shentry includes usage context (when to use it, optional argument), but thelist_cross_app_imports.pyentry only states its purpose. Consider adding invocation details and key arguments to match the usage guidance provided for the other script.📝 Example enhancement
-| [`list_cross_app_imports.py`](list_cross_app_imports.py) | Cross-app import report (Markdown/CSV). | +| [`list_cross_app_imports.py`](list_cross_app_imports.py) | Cross-app import report (Markdown/CSV). Run `python scripts/list_cross_app_imports.py [--format=md|csv]` to analyze imports between Django apps. |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/README.md` at line 8, Update the README entry for list_cross_app_imports.py to match the other scripts by adding invocation and key-argument guidance: describe how to run the script (e.g., python list_cross_app_imports.py [PATH] ), list important flags such as an optional target path argument, output options/format flag (Markdown/CSV), and a --help flag, and include a short example invocation showing output selection (e.g., generate Markdown or CSV). Reference the script name list_cross_app_imports.py and ensure the text mirrors the style and level of detail used for clean-macos.sh so users know when and how to run it and what outputs to expect.boost_usage_tracker/README.md (1)
38-40: ⚡ Quick winReplace placeholder descriptions with meaningful command summaries.
The management command descriptions currently just repeat the command name (e.g., "Management command: run_boost_usage_tracker"). Compare with
boost_library_tracker/README.mdlines 41-47, which provides helpful descriptions like "Backfill previous_filename_id for renamed files" and "Exit 0 if a new Boost release exists."Consider adding brief descriptions that explain what each command does without requiring
--help.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@boost_usage_tracker/README.md` around lines 38 - 40, Replace the placeholder descriptions for the management commands by writing concise, meaningful summaries for `run_boost_usage_tracker`, `run_update_created_repos_by_language`, and `run_update_db`; specifically: describe what each command does (e.g., `run_boost_usage_tracker` — scan project repos and aggregate Boost library usage metrics into the tracker DB, `run_update_created_repos_by_language` — compute or refresh language-based counts/meta for created repositories, `run_update_db` — apply incremental updates/migrations or backfill dataset fields in the tracker DB), and update the README table entries so each command row contains a one-line action summary rather than repeating the command name.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 198: The README table references a non-existent file; update the table
row for `boost_library_tracker/` by removing the linked path
`boost_library_tracker/management/commands/README.md` (or alternatively create
that README file if intended). Specifically, edit the table cell containing
"`Boost metadata + many maintenance commands; see also
[`management/commands/`](boost_library_tracker/management/commands/README.md).`"
and either remove the "see also" clause/link or add a new
`boost_library_tracker/management/commands/README.md` with the appropriate
content so the link resolves.
In `@wg21_paper_tracker/README.md`:
- Line 36: The README table entry for the management command currently repeats
the command name; update the description for import_wg21_metadata_from_csv to a
clear functional description such as "Import metadata from CSV" (or similar) so
readers understand what the command does; locate the table row containing the
symbol import_wg21_metadata_from_csv and replace the redundant second-column
text with the improved description.
- Around line 28-30: Remove the redundant "## Title" subsection and its
duplicated bold line ("**WG21 Paper Tracker**") from the README; locate the "##
Title" heading and the following bold text and delete those lines so the
document only keeps the original top-level title heading.
---
Nitpick comments:
In `@boost_usage_tracker/README.md`:
- Around line 38-40: Replace the placeholder descriptions for the management
commands by writing concise, meaningful summaries for `run_boost_usage_tracker`,
`run_update_created_repos_by_language`, and `run_update_db`; specifically:
describe what each command does (e.g., `run_boost_usage_tracker` — scan project
repos and aggregate Boost library usage metrics into the tracker DB,
`run_update_created_repos_by_language` — compute or refresh language-based
counts/meta for created repositories, `run_update_db` — apply incremental
updates/migrations or backfill dataset fields in the tracker DB), and update the
README table entries so each command row contains a one-line action summary
rather than repeating the command name.
In `@scripts/README.md`:
- Line 8: Update the README entry for list_cross_app_imports.py to match the
other scripts by adding invocation and key-argument guidance: describe how to
run the script (e.g., python list_cross_app_imports.py [PATH] ), list important
flags such as an optional target path argument, output options/format flag
(Markdown/CSV), and a --help flag, and include a short example invocation
showing output selection (e.g., generate Markdown or CSV). Reference the script
name list_cross_app_imports.py and ensure the text mirrors the style and level
of detail used for clean-macos.sh so users know when and how to run it and what
outputs to expect.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 3db39771-171a-4c81-8814-7ca65e977c36
📒 Files selected for processing (26)
README.mdboost_collector_runner/README.mdboost_library_docs_tracker/README.mdboost_library_tracker/README.mdboost_library_usage_dashboard/README.mdboost_mailing_list_tracker/README.mdboost_usage_tracker/README.mdclang_github_tracker/README.mdconfig/README.mdcore/README.mdcore/collectors/README.mdcore/operations/README.mdcore/operations/file_ops/README.mdcore/operations/github_ops/README.mdcore/operations/md_ops/README.mdcore/operations/slack_ops/README.mdcore/utils/README.mdcppa_pinecone_sync/README.mdcppa_slack_tracker/README.mdcppa_user_tracker/README.mdcppa_youtube_script_tracker/README.mddiscord_activity_tracker/README.mdgithub_activity_tracker/README.mdscripts/README.mdslack_event_handler/README.mdwg21_paper_tracker/README.md
…acker to improve clarity and organization
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@boost_library_tracker/README.md`:
- Around line 33-35: Remove the redundant "## Title" section that duplicates the
main heading by deleting the lines containing "## Title" and the bold "**Boost
Library Tracker**" under it (the template artifact between the top-level heading
and the rest of the README); keep the original top-level heading intact so the
README only contains a single main title.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 5c0bedd2-7cb3-4573-90ec-843d4649cd2f
📒 Files selected for processing (3)
README.mdboost_library_tracker/README.mdwg21_paper_tracker/README.md
… streamline documentation
Collaborator
There was a problem hiding this comment.
I don't believe that a readme is strictly necessary for general holders such as core and scripts. However, individual apps require a more detailed readme. It should reflect the workflow regarding what data is retrieved from where, how it is processed, where it is stored and when it is executed(daily/weekly or others).
Current all READMEs are too simple and those are uniform without individual app characteristics.
… detail in data workflows
…d detail in data workflows and service references
There was a problem hiding this comment.
🧹 Nitpick comments (1)
clang_github_tracker/README.md (1)
44-45: 💤 Low valueConsider simplifying the date option aliases.
Documenting three equivalent aliases (
--since,--from-date,--start-timeand--until,--to-date,--end-time) may confuse users about which to use. If all three are genuinely supported, consider noting a "preferred" option or documenting only the primary flag with a mention that aliases exist.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@clang_github_tracker/README.md` around lines 44 - 45, Pick and document a single preferred flag for each boundary (e.g., prefer --since and --until) and update the README lines showing `--since`, `--from-date`, `--start-time` and `--until`, `--to-date`, `--end-time` to present the preferred flag first with a parenthetical note that aliases exist (e.g., "--since (alias: --from-date, --start-time)") so the table is simpler and readers know the canonical flag while preserving alias information.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@clang_github_tracker/README.md`:
- Around line 44-45: Pick and document a single preferred flag for each boundary
(e.g., prefer --since and --until) and update the README lines showing
`--since`, `--from-date`, `--start-time` and `--until`, `--to-date`,
`--end-time` to present the preferred flag first with a parenthetical note that
aliases exist (e.g., "--since (alias: --from-date, --start-time)") so the table
is simpler and readers know the canonical flag while preserving alias
information.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: bdebe47d-d393-4a1c-b8f7-b0e9822270ec
📒 Files selected for processing (17)
boost_collector_runner/README.mdboost_library_docs_tracker/README.mdboost_library_tracker/README.mdboost_library_usage_dashboard/README.mdboost_mailing_list_tracker/README.mdboost_usage_tracker/README.mdclang_github_tracker/README.mdcore/README.mdcppa_pinecone_sync/README.mdcppa_slack_tracker/README.mdcppa_user_tracker/README.mdcppa_youtube_script_tracker/README.mddiscord_activity_tracker/README.mdgithub_activity_tracker/README.mdscripts/README.mdslack_event_handler/README.mdwg21_paper_tracker/README.md
✅ Files skipped from review due to trivial changes (6)
- scripts/README.md
- cppa_slack_tracker/README.md
- boost_mailing_list_tracker/README.md
- boost_library_docs_tracker/README.md
- wg21_paper_tracker/README.md
- discord_activity_tracker/README.md
…ation of directories and files
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 163: The project tree code fence in README.md is missing a language tag
causing markdownlint MD040; update the fenced block that starts with the project
tree (the triple backticks surrounding the " . ├── manage.py ..." tree) to use a
language tag by changing the opening backticks to ```text so the block becomes a
text code fence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
jonathanMLDev
approved these changes
May 19, 2026
…management command names and scheduling for Boost Data Collector
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
config/,core/(includingcollectors/,operations/*,utils/),boost_collector_runner/, andscripts/.Motivation
Contributors needed a faster way to discover what each package does, which
manage.pycommands matter, and which env vars are required—without reading every command module or only the long-formdocs/tree.Changes
Root
README.md.env.example).New READMEs (24 packages)
config/,boost_collector_runner/,scripts/core/,core/collectors/,core/operations/,core/operations/{github_ops,slack_ops,md_ops,file_ops}/,core/utils/slack_event_handlerEach app README typically includes: overview, common tasks, main
run_*command options, other management commands, and apytestone-liner.Out of scope
boost_collector_schedule.yamlchanges.migrations/,tests/, or mostmanagement/commands/subfolders (per root README policy).Test plan
*/README.md.python manage.py <command> --helpand confirm documented flags match (e.g.run_scheduled_collectors,run_cppa_user_tracker).Closes #220
Summary by CodeRabbit