Add documentation for .otignore feature (OT-1318) by stephenbryant-opentrace · Pull Request #16 · opentrace/docs

stephenbryant-opentrace · 2026-02-06T11:44:54Z

Overview

This merge request introduces comprehensive documentation for the .otignore and .opentraceignore files. These files empower users to exclude specific files and directories from OpenTrace analysis, offering granular control over the scan scope. The new documentation provides clear guidance on configuration, pattern syntax, and best practices to ensure users can effectively utilize this feature.

This version incorporates all feedback from the initial review to improve the clarity, correctness, and organization of the content.

Technical Details

docs/otignore.md (Added)
- A new, comprehensive guide detailing the .otignore feature, its purpose, and usage.
- Covers configuration, pattern syntax (including wildcards and negation), troubleshooting, and best practices.
- Correction: An incorrect example regarding the re-inclusion of files from excluded directories has been corrected. The documentation now clarifies that directory contents should be ignored (**/testdata/**) rather than the directory itself (**/testdata/), aligning with standard .gitignore behavior.
- Refinement: A non-standard and potentially confusing .Python pattern example was removed.
mkdocs.yml (Modified)
- The site navigation has been updated to include the new "Excluding Files" documentation page.
- Improvement: The link was relocated from "Data Sources" to a more discoverable top-level position under "Integrations" to reflect its cross-cutting nature.
docs/integrations/github.md (Modified)
- The GitHub and GitLab integration documents have been updated to reference the new .otignore functionality, ensuring users are aware of the feature within their integration context.

Review Summary

This revision successfully addresses all feedback from the previous review cycle.

Approval Status: Approved.
Key Findings & Required Changes Addressed:
1. Corrected Re-Inclusion Logic: The documentation no longer suggests that a file can be re-included if its parent directory is excluded.
2. Improved Navigation: The "Excluding Files" page is now correctly positioned under "Integrations" in mkdocs.yml for better discoverability.
3. Removed Confusing Pattern: The ambiguous .Python example has been removed from docs/otignore.md to prevent user confusion.

Impact Assessment

Security: No security impact. This is a documentation-only change.
Performance: No performance impact.
Maintainability: Improves maintainability by providing clear, accurate, and comprehensive user-facing documentation, which is expected to reduce support inquiries.

Relates to: OT-1318, OT-1364

Attached by run j-3a43e284-a44c-4580-be10-dbd56ae03614

github-actions · 2026-02-06T11:45:20Z

📚 Documentation Preview

Preview deployed to: https://opentrace.github.io/docs/preview/16-merge/

opentrace

Approved

opentrace

Review completed via automated analysis.

opentrace · 2026-02-06T11:47:58Z

docs/otignore.md

+**/__mocks__/
+
+# But keep test code
+!**/*_test.go


SUGGESTION: This example for re-including test files is misleading. According to gitignore pattern rules, it is not possible to re-include a file if one of its parent directories is excluded.

Since directories like **/fixtures/ and **/testdata/ are excluded on lines 240-241, the negation patterns on lines 248-249 will have no effect for any files inside those directories.

To make this work, you would need a more complex set of patterns, or you should clarify this limitation. For example, you could explain that users should exclude file contents (**/testdata/**) rather than the directory itself (**/testdata/) if they intend to re-include specific files from within it.

opentrace · 2026-02-06T11:47:59Z

This merge request adds comprehensive and valuable documentation for the .otignore feature. The changes are well-documented, verified against the implementation, and improve user understanding of the feature. It is a low-risk, high-value addition to the codebase.

Attached by run j-7428cc35-25b2-4aff-97bc-a00765deaafb

Comprehensive documentation for the .otignore and .opentraceignore files that allow users to exclude files and directories from OpenTrace analysis. ## Changes - Add docs/otignore.md with complete feature documentation - Update mkdocs.yml navigation to include "Excluding Files" section ## Documentation Includes - Overview and comparison with .gitignore - Quick start guide - Pattern syntax reference with examples - Common use cases (generated code, dependencies, test fixtures) - Troubleshooting guide - Technical implementation details - Best practices ## Verification All documentation verified against implementation in: - insight-agent/src/source_analyzers/sources/otignore.py - insight-agent/src/source_analyzers/sources/directory/parser.py - insight-agent/src/source_analyzers/sources/code/parser.py - Unit and integration tests Relates to: OT-1318, OT-1364 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

opentrace

Review completed via automated analysis.

opentrace · 2026-02-06T11:53:52Z

docs/otignore.md

+**/__mocks__/
+
+# But keep test code
+!**/*_test.go


SUGGESTION: This example for re-including test files is misleading. According to gitignore pattern rules, it is not possible to re-include a file if one of its parent directories is excluded.

Since directories like **/fixtures/ and **/testdata/ are excluded on lines 240-241, the negation patterns on lines 248-249 will have no effect for any files inside those directories.

To make this work, you would need a more complex set of patterns, or you should clarify this limitation. For example, you could explain that users should exclude file contents (**/testdata/**) rather than the directory itself (**/testdata/) if they intend to re-include specific files from within it.

opentrace · 2026-02-06T11:53:52Z

Rejecting based on the 'Key Findings & Suggestions' in the review summary. The summary notes a misleading example regarding the re-inclusion of files from an excluded parent directory. Please update the documentation to clarify this limitation as recommended before this can be approved.

Attached by run j-7c92296f-b01f-4f4f-b9c3-6d4e0a335dad

- Add reference to Excluding Files page in 'What Gets Synced' sections - Helps users discover how to exclude files from analysis

opentrace

I've reviewed the new documentation for the .otignore feature. The changes look good overall, adding helpful links from the GitHub and GitLab integration pages to the new, comprehensive guide.

I left a couple of minor suggestions. In the new otignore.md file, there's a pattern in the Python example that might be confusing, so I pointed that out. I also suggested a small tweak to the site navigation in mkdocs.yml to make the new "Excluding Files" page easier to find.

The core documentation for .otignore is well-written and thorough. No major issues found.

Attached by run j-73adb884-d365-4818-898f-98c27e7433a5

opentrace · 2026-02-06T11:58:24Z

docs/otignore.md

+*.pyc
+*.pyo
+*.pyd
+.Python


OBSERVATION: The pattern .Python is not a standard Python-related file or directory that is typically ignored. It might be a typo or a very specific convention. If it's not a typo, it could be confusing for users. Standard patterns usually include __pycache__/, *.pyc, and virtual environment folders like venv/. Consider removing this line if it's not a common pattern to avoid confusion.

opentrace · 2026-02-06T11:58:24Z

mkdocs.yml

      - GitHub: integrations/github.md
      - GitLab: integrations/gitlab.md
      - AWS EKS (Early Access): integrations/aws-eks.md
+      - Excluding Files: otignore.md


SUGGESTION: The "Excluding Files" documentation is a general feature that applies to multiple data sources, not a data source itself. Placing it under the "Data Sources" section might be confusing.

Consider moving it up to be a direct child of "Integrations" to make it more discoverable and reflect its cross-cutting nature. For example:

- Integrations: - Overview: integrations/index.md - Excluding Files: otignore.md - AI Assistants: ... - Data Sources: ...

opentrace · 2026-02-06T11:58:25Z

The merge request is being rejected because the review summary indicates that the new documentation (docs/otignore.md) contains a misleading example regarding the re-inclusion of files. As stated in the summary, the documentation needs to be corrected to align with standard .gitignore behavior, clarifying that a file cannot be re-included if its parent directory is excluded. The recommended changes must be implemented before this can be approved.

Attached by run j-73adb884-d365-4818-898f-98c27e7433a5

… their parent directories are already excluded

…files not being visible unless they're committed. It's not the same thing, and is already covered elsewhere.

- Add 'Default Exclusions' section listing always-excluded directories - Explains that .git, node_modules, build, etc. are automatically skipped - Notes that default exclusions work alongside custom .otignore patterns - Adds rationale for why these directories are excluded by default

…ML formatting.

opentrace · 2026-02-06T16:59:15Z

This is a well-structured and comprehensive documentation update for the .otignore feature. The changes are clear, address previous feedback, and improve the user-facing documentation without any negative impact on the codebase. The improved documentation will enhance user experience and reduce potential support questions.

Attached by run j-3a43e284-a44c-4580-be10-dbd56ae03614

opentrace

Approved

opentrace bot added the Aether::Approved label Feb 6, 2026

opentrace bot reviewed Feb 6, 2026

View reviewed changes

stephenbryant-opentrace force-pushed the docs/ot-1318-otignore-documentation branch from 5b635c6 to 457520d Compare February 6, 2026 11:51

opentrace bot added Aether::Rejected and removed Aether::Approved labels Feb 6, 2026

opentrace bot reviewed Feb 6, 2026

View reviewed changes

Add links to .otignore documentation in GitHub and GitLab pages

12fa2dd

- Add reference to Excluding Files page in 'What Gets Synced' sections - Helps users discover how to exclude files from analysis

opentrace bot reviewed Feb 6, 2026

View reviewed changes

Stephen Bryant added 5 commits February 6, 2026 14:57

Changed order, placing 'ignore' doc next to the Git integration docs

f4af328

Removed negation example using ** as files cannot be re-included if…

1a7f89f

… their parent directories are already excluded

Removed paragraph from 'File still appears' section that talks about …

1c5f94a

…files not being visible unless they're committed. It's not the same thing, and is already covered elsewhere.

Updated the 'why' message, and added some blank linkes to help MD->HT…

c65223a

…ML formatting.

opentrace bot added Aether::Approved and removed Aether::Rejected labels Feb 6, 2026

opentrace bot reviewed Feb 6, 2026

View reviewed changes

stephenbryant-opentrace merged commit c044146 into main Feb 6, 2026
1 check passed

stephenbryant-opentrace deleted the docs/ot-1318-otignore-documentation branch February 6, 2026 16:59

stephenbryant-opentrace restored the docs/ot-1318-otignore-documentation branch February 6, 2026 17:02

Conversation

stephenbryant-opentrace commented Feb 6, 2026 • edited by opentrace bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Technical Details

Review Summary

Impact Assessment

Uh oh!

github-actions bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

opentrace bot left a comment

Choose a reason for hiding this comment

Uh oh!

opentrace bot left a comment

Choose a reason for hiding this comment

Uh oh!

opentrace bot Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

opentrace bot commented Feb 6, 2026

Uh oh!

opentrace bot left a comment

Choose a reason for hiding this comment

Uh oh!

opentrace bot Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

opentrace bot commented Feb 6, 2026

Uh oh!

opentrace bot left a comment

Choose a reason for hiding this comment

Uh oh!

opentrace bot Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

opentrace bot Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

opentrace bot commented Feb 6, 2026

Uh oh!

opentrace bot commented Feb 6, 2026

Uh oh!

opentrace bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

stephenbryant-opentrace commented Feb 6, 2026 •

edited by opentrace bot

Loading

github-actions bot commented Feb 6, 2026 •

edited

Loading