feat(ci): implement flat-file automated documentation architecture#77
Conversation
|
Note
|
| Layer / File(s) | Summary |
|---|---|
Tag trigger pattern updates .github/workflows/changelog.yml |
push.tags patterns expanded to match both v-prefixed and plain semantic-version tags, including pre-release suffixes. |
Flat version file generation and README rebuild .github/workflows/changelog.yml |
Replaced per-version directory scaffolding with creation of docs/<version>.md containing the changelog and regenerated docs/README.md by embedding the latest version and appending a reverse sort -V -r "Version History" from docs/*.md (excluding README). |
Automated commit and push .github/workflows/changelog.yml |
Workflow now checks out the default branch, retries a fast-forward git pull up to 3 times with exponential backoff, stages docs/, exits without committing when git diff --cached is empty, and commits changes with a flat-documentation message including [skip ci]. |
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
- KDM-cli/kdm-cli#43: Prior PR that introduced versioned
docs/<version>/scaffolding which this change replaces with flatdocs/<version>.mdfiles and a rebuilt README.
Suggested reviewers
- utkarsh232005
Poem
📚 From tags both plain and prefixed we scan,
Changelogs now live in a single-file plan.
README rebuilt with versions aligned,
Empty commits skipped, retries defined —
Automation hums; docs shine, well-timed. ✨
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Title check | ✅ Passed | The PR title accurately describes the main architectural change: transitioning from nested-directory documentation to a flat-file structure in the CI/CD workflow. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
| Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
Comment @coderabbitai help to get the list of available commands and usage tips.
github-actions
Bot
added
ci/cd
documentation
|
@utkarsh232005 assign me for this PR |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
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 @.github/workflows/changelog.yml:
- Around line 71-75: The loop that builds the version history currently uses the
glob "docs/v*.md" and a plain ls which will omit non-v-prefixed release files
and fail if no matches exist; replace it by enabling safe globbing (shopt -s
nullglob), collecting all docs/*.md except README.md into an array (e.g.,
version_files via mapfile or similar), sort that list with sort -V -r, then
iterate over that array to produce entries written to "$TEMP_README" by
computing each V_NAME with basename (basename "$file" .md) and echoing "*
[$V_NAME]($V_NAME.md)" — this preserves the existing V_NAME and TEMP_README
usage while including all release files and avoiding errors on empty globs.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 13f63499-823b-4f8e-8583-c63e88304798
⛔ Files ignored due to path filters (6)
docs/README.mdis excluded by none and included by nonedocs/v1.2.1/config/README.mdis excluded by none and included by nonedocs/v1.2.1/health/README.mdis excluded by none and included by nonedocs/v1.2.1/logs/README.mdis excluded by none and included by nonedocs/v1.2.1/show/README.mdis excluded by none and included by nonedocs/v1.2.1/watch/README.mdis excluded by none and included by none
📒 Files selected for processing (1)
.github/workflows/changelog.yml
|
link issue #46 with this pr |
|
Hey @Yuvraj-Sarathe did you test the action properly before merging please provide some ss so that we can have clear picture of what will be the outcome of this pr. |
wait before merging! coderabbit found a good detail because I saw your releases and it though does not use beta but do use v1.0.1-alpha.1 I am editing the file and then we can proceed |
Updated changelog workflow to support additional version formats and improved file handling.
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/changelog.yml (1)
3-11: 🧹 Nitpick | 🔵 Trivial | ⚖️ Poor tradeoffConsider adding workflow_dispatch for testing.
The workflow currently only triggers on release publication or tag pushes, making it difficult to test changes without creating actual releases. Adding a
workflow_dispatchtrigger would enable manual testing:on: release: types: [published] push: tags: - 'v*.*.*' - '*.*.*' - 'v*.*.*-*' - '*.*.*-*' + workflow_dispatch: + inputs: + test_version: + description: 'Test version tag (e.g., v1.0.0-test)' + required: true + type: stringThen reference
inputs.test_versionorgithub.ref_nameconditionally in the VERSION assignment. This addresses the testing evidence requested by the reviewer without requiring actual release tags.🤖 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 @.github/workflows/changelog.yml around lines 3 - 11, Add a manual trigger to the workflow by adding workflow_dispatch under the existing on: block and define an input (e.g., test_version) so reviewers can run the workflow manually; then update the VERSION assignment logic (where you currently derive the version from github.ref_name) to prefer inputs.test_version when present (fall back to github.ref_name) so manual runs can supply a test version without requiring tags or releases.
🤖 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 @.github/workflows/changelog.yml:
- Around line 8-11: The four tag globs are redundant; keep only the two base
patterns 'v*.*.*' and '*.*.*' and remove the pre-release-specific entries
'v*.*.*-*' and '*.*.*-*' because the existing globs already match tags with
suffixes (the '*' can cover pre-release suffixes); update the workflow to delete
the two '-*' patterns so only 'v*.*.*' and '*.*.*' remain.
- Around line 51-52: The workflow uses github.ref_name directly to construct
VERSION and VERSION_FILE which allows path traversal; validate and sanitize
github.ref_name before building VERSION_FILE by ensuring VERSION matches an
allowed pattern (e.g., strict semver or a whitelist) and reject or normalize any
values containing path separators or traversal sequences; update the step that
sets VERSION/VERSION_FILE to perform this validation and only set
VERSION_FILE="docs/${VERSION}.md" when the sanitized VERSION passes (otherwise
fail the job or skip creating the file).
- Line 61: The script creates a temporary file via TEMP_README=$(mktemp) but
doesn't remove it on failure; add a trap that removes "$TEMP_README" on EXIT (or
ERR/INT) so the temp file is cleaned up if the script exits before the later mv
operation (the existing mv that moves TEMP_README should remain unchanged);
implement the trap immediately after the mktemp assignment so TEMP_README is
always registered for cleanup.
- Line 98: Replace the raw git pull command "git pull origin ${{
github.event.repository.default_branch }} --ff-only" with a small
retry-and-failure handler: run a shell that attempts the pull up to N times with
a short backoff (e.g., for i in 1..3; do git pull ... --ff-only && break ||
sleep $((i*2)); done), and if all attempts fail emit a clear error message and
exit non‑zero (e.g., >&2 echo "Fast-forward pull failed after retries:
<details>" && exit 1); ensure the step logs the failing git output for context.
---
Outside diff comments:
In @.github/workflows/changelog.yml:
- Around line 3-11: Add a manual trigger to the workflow by adding
workflow_dispatch under the existing on: block and define an input (e.g.,
test_version) so reviewers can run the workflow manually; then update the
VERSION assignment logic (where you currently derive the version from
github.ref_name) to prefer inputs.test_version when present (fall back to
github.ref_name) so manual runs can supply a test version without requiring tags
or releases.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 217ed8eb-3cb3-4519-82e1-fae2c4c753ae
📒 Files selected for processing (1)
.github/workflows/changelog.yml
|
Actions Confirmation (tested on a fake release tag): Readme and Changelog confirmation from main branch (the previous ones are not here because the tags are not there in the forked repo): 
The folder is there in the main branch, but the branch I am merging this from deleted that repo. The details are empty because the test tag was empty. |
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 @.github/workflows/changelog.yml:
- Around line 97-98: The workflow contains a duplicated checkout step ("git
checkout ${{ github.event.repository.default_branch }}") executed twice in
succession; remove the redundant second occurrence so only a single checkout
command remains (locate the duplicate occurrences of the checkout command in the
changelog.yml workflow and delete the repeated line).
- Around line 51-52: The workflow uses direct `${{ github.ref_name }}`
interpolation into a run script (variables VERSION and VERSION_FILE), which can
allow shell injection; instead set VERSION via the job/step env: block (e.g.,
env: VERSION: ${{ github.ref_name }}) and then reference the environment
variable inside the run step (use the shell-safe env value) so the runner does
not evaluate shell metacharacters; keep VERSION_FILE constructed from that env
var (e.g., VERSION_FILE="docs/${VERSION}.md"), and optionally add a validation
step that checks VERSION against a restrictive regex before using it.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: b4a09a5f-0e17-4abe-a2bd-eb075afa930f
📒 Files selected for processing (1)
.github/workflows/changelog.yml
|
@utkarsh232005 ready to merge! |
Looks great @Yuvraj-Sarathe amazing work merging this as is now. |
|
2 participants
Overview
This PR completely overhauls the automated documentation system inside the
docs/directory to implement a flat-file architecture (Option 1). The previous nested directory setup (docs/v1.x.x/along with its fallback folders) has been completely removed to eliminate repository bloat and improve scannability.With this new pipeline, all historical versions will exist as standalone markdown files directly in the root of the
docs/folder, whiledocs/README.mdwill dynamically serve as the main landing page, embedding the latest release notes automatically.Changes Made
Updated
.github/workflows/changelog.yml: * Replaced the nested directory generation logic with a clean, flat-file generation script.Integrated dynamic content ingestion to inject the raw markdown text of the latest version file straight into
docs/README.md.Added reverse-chronological sorting (
sort -V -r) to automatically maintain an ordered version history list at the bottom of the main README.Appended the
[skip ci]tag to the automated commit string to prevent recursive GitHub Actions execution loops.Cleaned Repository Layout: Removed old, unused placeholder subdirectories within
docs/to ground the new flat layout baseline.New Target Architecture Layout
Verification & Testing Plan
v*.*.*pattern or publishing an official GitHub release.docs/v1.2.1.md), and safely overwritesdocs/README.mdusing atomic file moving (mv) to prevent data truncation.Summary by CodeRabbit