feat(docs): add comprehensive migration guide for custom template users - #114
Conversation
🎉 Snyk checks have passed. No issues have been found so far.✅ security/snyk check is complete. No issues have been found. (View Details) |
Co-authored-by: unclesp1d3r <251112+unclesp1d3r@users.noreply.github.com>
|
Caution Review failedFailed to post review comments Summary by CodeRabbit
WalkthroughThis PR adds comprehensive documentation and a migration validation script to support users transitioning from template-based markdown generation to programmatic methods in v2.0, including Copilot guidance, migration examples, and automated validation tooling. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes
Possibly related PRs
Suggested labels
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
… error handling guidelines - Added comprehensive guidance for GitHub Copilot, emphasizing the importance of AGENTS.md as the primary reference for AI assistant behavior. - Included examples for error handling and structured logging patterns using `charmbracelet/log`. - Updated the AI agent code review checklist to reflect new standards for error context and logging practices. - Improved project structure documentation for clarity and reference. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
coderabbitai
Bot
added
documentation
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive migration documentation and tooling to help users transition from custom templates to the new programmatic markdown generation approach in opnDossier v2.0. The migration guide provides function mappings, code examples, and best practices, while the validation script automates testing and comparison of the two generation modes.
Key changes:
- Added 470-line migration guide with function mappings, migration patterns, and troubleshooting
- Created 186-line validation script to automate migration testing and comparison
- Updated Copilot instructions with clarifications on error handling, logging, and configuration management patterns
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
docs/migration-guide.md |
Comprehensive migration guide with function mappings, code examples, testing strategies, and FAQ for transitioning from templates to programmatic generation |
scripts/validate-migration.sh |
Bash script to validate migrations by comparing template vs programmatic output, testing multiple formats, and providing performance comparisons |
.github/copilot-instructions.md |
Added code examples for error handling, structured logging, and configuration management; improved checklist formatting and clarifications |
| programmaticcOutput := builder.BuildReport(config) | ||
|
|
||
| // Verify key content is present | ||
| assert.Contains(t, programmaticcOutput, "System Information") | ||
| assert.Contains(t, programmaticcOutput, "Security Assessment") |
There was a problem hiding this comment.
Corrected spelling of 'programmaticc' to 'programmatic'
| programmaticcOutput := builder.BuildReport(config) | |
| // Verify key content is present | |
| assert.Contains(t, programmaticcOutput, "System Information") | |
| assert.Contains(t, programmaticcOutput, "Security Assessment") | |
| programmaticOutput := builder.BuildReport(config) | |
| // Verify key content is present | |
| assert.Contains(t, programmaticOutput, "System Information") | |
| assert.Contains(t, programmaticOutput, "Security Assessment") |
| if find ./templates -name "*.tmpl" -o -name "*.tpl" 2>/dev/null | grep -q .; then | ||
| find ./templates -name "*.tmpl" -o -name "*.tpl" -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/' |
There was a problem hiding this comment.
The find command with -o operator requires parentheses for correct grouping. Without parentheses, the precedence causes the 2>/dev/null redirection to only apply to the second -name test. Change to: find ./templates \( -name "*.tmpl" -o -name "*.tpl" \) 2>/dev/null | grep -q .; then
| if find ./templates -name "*.tmpl" -o -name "*.tpl" 2>/dev/null | grep -q .; then | |
| find ./templates -name "*.tmpl" -o -name "*.tpl" -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/' | |
| if find ./templates \( -name "*.tmpl" -o -name "*.tpl" \) 2>/dev/null | grep -q .; then | |
| find ./templates \( -name "*.tmpl" -o -name "*.tpl" \) -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/' |
| echo "" | ||
| echo "Template functions in use:" | ||
| if find ./templates -name "*.tmpl" -o -name "*.tpl" 2>/dev/null | grep -q .; then | ||
| find ./templates -name "*.tmpl" -o -name "*.tpl" -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/' |
There was a problem hiding this comment.
Same issue as Comment 2. The find command's -o operator needs parentheses for correct grouping. Change to: find ./templates \( -name "*.tmpl" -o -name "*.tpl" \) -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/'
| find ./templates -name "*.tmpl" -o -name "*.tpl" -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/' | |
| find ./templates \( -name "*.tmpl" -o -name "*.tpl" \) -exec grep -h -o '{{ [a-zA-Z][a-zA-Z0-9_]* ' {} \; | sort -u | sed 's/{{/ -/' |
| # Check if equivalent methods exist by looking at the source | ||
| if [ -d "./internal/converter" ]; then | ||
| echo "Available MarkdownBuilder methods:" | ||
| grep -h "func (b \*MarkdownBuilder)" ./internal/converter/*.go | grep -v "_test.go" | sed 's/func (b \*MarkdownBuilder) / - /' | sed 's/(.*$/()/' | sort |
There was a problem hiding this comment.
The grep -v "_test.go" filter on filenames won't work correctly here because the first grep operates on file contents, not filenames. To exclude test files, modify the glob pattern or use find with exclusions. Example: find ./internal/converter -name "*.go" ! -name "*_test.go" -exec grep -h "func (b \*MarkdownBuilder)" {} \; | sed 's/func (b \*MarkdownBuilder) / - /' | sed 's/(.*$/()/' | sort
| grep -h "func (b \*MarkdownBuilder)" ./internal/converter/*.go | grep -v "_test.go" | sed 's/func (b \*MarkdownBuilder) / - /' | sed 's/(.*$/()/' | sort | |
| find ./internal/converter -name "*.go" ! -name "*_test.go" -exec grep -h "func (b \*MarkdownBuilder)" {} \; | sed 's/func (b \*MarkdownBuilder) / - /' | sed 's/(.*$/()/' | sort |
| print_status $YELLOW "⚠ Reports differ - see migration-diff.txt for details" | ||
| echo "Difference summary:" | ||
| head -20 migration-diff.txt | ||
| if [ $(wc -l < migration-diff.txt) -gt 20 ]; then |
There was a problem hiding this comment.
Command substitution without quotes can cause word splitting issues. Quote the command substitution for safety: if [ "$(wc -l < migration-diff.txt)" -gt 20 ]; then
| if [ $(wc -l < migration-diff.txt) -gt 20 ]; then | |
| if [ "$(wc -l < migration-diff.txt)" -gt 20 ]; then |
…g settings - Modified generateWithHybridGenerator to set opt.UseTemplateEngine based on CLI flag precedence. - This change ensures that user-specified CLI flags take priority over configuration file settings, improving flexibility in template engine selection. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
- Updated logging initialization to determine log level based on verbose and quiet flags, removing reliance on deprecated GetLogLevel and GetLogFormat methods. - Replaced string concatenation with strings.Builder for performance improvements in error message formatting. - Removed unnecessary build constraints from integration and completeness test files, simplifying the build process. - Marked Error function in display package as deprecated in favor of StyleSheet.ErrorPrint. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
- Enhanced the migration guide with a detailed deprecation timeline and migration checklist to assist users in transitioning from template to programmatic methods. - Updated the custom template function mapping table to reflect the current status of functions, marking several as migrated and providing implementation details. - Improved the validation script for migration, adding checks for custom templates and ensuring users are informed about unmigrated functions. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
|
This pull request sets up GitHub code scanning for this repository. Once the scans have completed and the checks have passed, the analysis results for this pull request branch will appear on this overview. Once you merge this pull request, the 'Security' tab will show more code scanning analysis results (for example, for the default branch). Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results. For more information about GitHub code scanning, check out the documentation. |
![github-advanced-security[bot]](https://webproxy.poorya-velaei-d67.workers.dev/https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| - name: Setup golangci-lint | ||
| if: runner.os != 'Windows' | ||
| uses: golangci/golangci-lint-action@v8.0.0 | ||
| - uses: extractions/setup-just@v3 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
|
|
||
| - name: Install dependencies | ||
| run: go mod download | ||
| - uses: extractions/setup-just@v3 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
| with: | ||
| go-version: ${{ env.GO_VERSION }} | ||
|
|
||
| - uses: extractions/setup-just@v3 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Consolidate user story formatting for better readability and consistency throughout the user_stories.md file. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
- Updated template cache creation functions to handle errors gracefully. - Modified generation engine determination to return errors for unknown types. - Improved test cases to validate error scenarios. - Refactored code for better readability and maintainability. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
- Removed checkmarks from migration guide and function mapping for clarity. - Updated compliance report formatting for consistency. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
- Updated error handling to exit on error/unset vars. - Introduced a consistent warning printing function. - Replaced direct status prints with warning function for clarity. Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
This PR implements a comprehensive migration guide and validation tools to help users transition from custom templates to the new programmatic generation approach introduced in v2.0.
What's Added
Migration Guide (
docs/migration-guide.md)A comprehensive 650+ line guide that provides:
--use-templateflag or migrate to the recommended programmatic approachgetRiskLevel()→AssessRiskLevel(),filterTunables()→FilterSystemTunables(), and Sprig replacementsMigration Validator (
scripts/validate-migration.sh)A production-ready validation script that:
Example Usage
Technical Details
The implementation is based on actual codebase analysis, ensuring accurate function mappings to existing MarkdownBuilder methods in
internal/converter/markdown_*.go. The migration guide references real functions likeformatInterfacesAsLinks(),markdown.FormatBoolean(), and builder methods likeTruncateDescription()andAssessRiskLevel().Migration Timeline
This provides users a clear migration path while maintaining backward compatibility and taking advantage of the significant performance improvements in programmatic generation.
Fixes #97.
💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.