docs: seed Golden Context#336
Conversation
Add ARCHITECTURE.md, AGENTS.md, 7 ADRs, Bito review config, docs/specs scaffold, and agent navigation sections to README and CONTRIBUTING. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Changelist by BitoThis pull request implements the following key changes.
|
|
| Source | Requirement / Code Area | Status | Notes |
|---|---|---|---|
| DX-822, DX-843 | Create a reproducible dev environment for the contentful.java SDK | ✅ Met | Requirement already implemented in existing code at .devcontainer/devcontainer.json and .devcontainer/Dockerfile. |
| .bito.yaml, domain-invariants.txt, repo-truth-and-boundaries.txt, review-posture.txt, AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, 0001-maven-as-build-tool.md, 0002-retrofit-okhttp-as-http-layer.md, 0003-rxjava3-reactive-access.md, 0004-automatic-link-resolution.md, 0005-devcontainer-for-reproducible-dev-env.md, 0006-transform-query-annotation-mapping.md, 0007-cross-space-reference-resolution.md, README.md, README.md | Added development tooling and documentation files including .bito.yaml, .bito/guidelines/domain-invariants.txt, .bito/guidelines/repo-truth-and-boundaries.txt, .bito/guidelines/review-posture.txt, AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, docs/ADRs/0001-maven-as-build-tool.md, docs/ADRs/0002-retrofit-okhttp-as-http-layer.md, docs/ADRs/0003-rxjava3-reactive-access.md, docs/ADRs/0004-automatic-link-resolution.md, docs/ADRs/0005-devcontainer-for-reproducible-dev-env.md, docs/ADRs/0006-transform-query-annotation-mapping.md, docs/ADRs/0007-cross-space-reference-resolution.md, docs/ADRs/README.md, and docs/specs/README.md. | ⭕ Out of Scope | Added development tooling and documentation files including .bito.yaml, .bito/guidelines/domain-invariants.txt, .bito/guidelines/repo-truth-and-boundaries.txt, .bito/guidelines/review-posture.txt, AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, docs/ADRs/0001-maven-as-build-tool.md, docs/ADRs/0002-retrofit-okhttp-as-http-layer.md, docs/ADRs/0003-rxjava3-reactive-access.md, docs/ADRs/0004-automatic-link-resolution.md, docs/ADRs/0005-devcontainer-for-reproducible-dev-env.md, docs/ADRs/0006-transform-query-annotation-mapping.md, docs/ADRs/0007-cross-space-reference-resolution.md, docs/ADRs/README.md, and docs/specs/README.md. |
Impact Analysis by BitoInteraction DiagramsequenceDiagram
participant Dev as Developer
participant Repo as Repository
participant Config as .bito.yaml<br/>🟩 Added | ●●○ Medium
Dev->>Repo: Submit MR with new configuration files
Repo->>Config: Add .bito.yaml with guidelines
Config->>Repo: File created successfully
Repo->>Dev: MR ready for review
Dev->>Repo: Review guidelines in .bito.yaml
Repo->>Dev: Guidelines applied to future reviews
Dev->>Repo: Merge MR
Repo->>Config: Persist configuration
Config->>Repo: Configuration active
Repo->>Dev: Changes deployed
Dev->>Repo: Confirm no code functionality changed
This MR adds configuration and documentation files (.bito.yaml and associated guidelines) to improve review processes and document invariants, but does not modify any code functionality or system behavior. No upstream or downstream impacts detected in repository scan or cross-repo dependency analysis. Code Paths AnalyzedImpact: Flow: Direct Changes (Diff Files): Repository Impact: Cross-Repository Dependencies: Database/Caching Impact: API Contract Violations: Infrastructure Dependencies: Additional Insights: Testing RecommendationsFrontend Impact: Service Integration: Data Serialization: Privacy Compliance: Backward Compatibility: OAuth Functionality: Reliability Testing: Additional Insights: Analysis based on known dependency patterns and edges. Actual impact may vary. |
![bito-code-review[bot]](https://avatars.githubusercontent.com/in/1061978?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review Agent Run #23d976
Actionable Suggestions - 4
-
CONTRIBUTING.md - 1
- Inaccurate Integration Test Docs · Line 47-48
-
ARCHITECTURE.md - 1
- Misleading link resolution doc · Line 52-52
-
AGENTS.md - 1
- Incorrect Default Documentation · Line 29-29
-
docs/ADRs/0006-transform-query-annotation-mapping.md - 1
- Grammar Typo · Line 11-11
Review Details
-
Files reviewed - 17 · Commit Range:
4208397..4208397- .bito.yaml
- .bito/guidelines/domain-invariants.txt
- .bito/guidelines/repo-truth-and-boundaries.txt
- .bito/guidelines/review-posture.txt
- AGENTS.md
- ARCHITECTURE.md
- CONTRIBUTING.md
- README.md
- docs/ADRs/0001-maven-as-build-tool.md
- docs/ADRs/0002-retrofit-okhttp-as-http-layer.md
- docs/ADRs/0003-rxjava3-reactive-access.md
- docs/ADRs/0004-automatic-link-resolution.md
- docs/ADRs/0005-devcontainer-for-reproducible-dev-env.md
- docs/ADRs/0006-transform-query-annotation-mapping.md
- docs/ADRs/0007-cross-space-reference-resolution.md
- docs/ADRs/README.md
- docs/specs/README.md
-
Files skipped - 0
-
Tools
- Whispers (Secret Scanner) - ✔︎ Successful
- Detect-secrets (Secret Scanner) - ✔︎ Successful
Bito Usage Guide
Commands
Type the following command in the pull request comment and save the comment.
-
/review- Manually triggers a full AI review. -
/pause- Pauses automatic reviews on this pull request. -
/resume- Resumes automatic reviews. -
/resolve- Marks all Bito-posted review comments as resolved. -
/abort- Cancels all in-progress reviews.
Refer to the documentation for additional commands.
Configuration
This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.
Documentation & Help
AI Code Review powered by
| - **Integration tests** require a live Contentful space and environment variables — not run in CI by default. | ||
|
|
There was a problem hiding this comment.
The documentation states that integration tests require environment variables and are not run in CI by default, but inspection shows they use hardcoded values (e.g., space 'cfexampleapi') and are included in the CI 'mvn test' run. This could mislead contributors.
Code Review Run #23d976
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
| - `ResourceUtils.mapResources()` — indexes assets and entries by ID | ||
| - `ResourceUtils.setRawFields()` — preserves the unprocessed field map for rich text access | ||
| - `RichTextFactory.resolveRichTextField()` — parses rich text JSON into the `CDARich*` node tree | ||
| - `ResourceUtils.resolveLinks()` — traverses the includes and replaces link stubs with the actual `CDAResource` objects (in-memory object graph) |
There was a problem hiding this comment.
The description of ResourceUtils.resolveLinks() implies all link stubs are replaced with actual objects, but per ADR 0004 and AGENTS.md, unresolved links beyond depth 10 remain as placeholders. This could mislead developers expecting complete resolution.
Citations
- Rule Violated: AGENTS.md:21
Code Review Run #23d976
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
| - **Android: never depend on `okhttp-jvm` directly when using `okhttp-android`** — exclude `okhttp-jvm` from this library to avoid duplicate-class errors on Android (see README and ADR 0002). | ||
| - **`TlsSocketFactory` only activates below Android API 20** — do not remove or gate it differently; it protects older devices. | ||
| - **`TransformQuery.observeAndTransform()` auto-injects a `select` filter** — if the annotation scanner has a bug, fields are silently dropped, not thrown as errors. Always validate field mapping in tests. | ||
| - **`logSensitiveData` defaults to `false`** — never flip this to `true` in production builds; auth tokens would be logged. |
There was a problem hiding this comment.
The documentation claims logSensitiveData defaults to false, but CDAClient.java line 583 initializes it to true in the Builder. This inconsistency could mislead developers about the default logging behavior for sensitive data.
Code Review Run #23d976
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
|
|
||
| ## Context | ||
|
|
||
| Consumers often want to map CDA Entry responses to their own domain model classes rather than working with the generic `CDAEntry` + field maps. Without a mapping layer, consumers write repetitive boilerplate to extract typed fields from `CDAEntry.getField()`. A code generation approach (similar to ORM annotation processors) was considered but adds build complexity. |
There was a problem hiding this comment.
The '+' in 'generic CDAEntry + field maps' should be 'and' to fix the grammar error in the ADR context.
Code suggestion
Check the AI-generated fix before applying
| Consumers often want to map CDA Entry responses to their own domain model classes rather than working with the generic `CDAEntry` + field maps. Without a mapping layer, consumers write repetitive boilerplate to extract typed fields from `CDAEntry.getField()`. A code generation approach (similar to ORM annotation processors) was considered but adds build complexity. | |
| Consumers often want to map CDA Entry responses to their own domain model classes rather than working with the generic `CDAEntry` and field maps. Without a mapping layer, consumers write repetitive boilerplate to extract typed fields from `CDAEntry.getField()`. A code generation approach (similar to ORM annotation processors) was considered but adds build complexity. |
Code Review Run #23d976
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
✅ Review Settings OverriddenStatus: Guidelines:
Note: Extra guidelines beyond 3 general purpose guidelines and 1 language specific guideline per language are not processed. Guidelines are fetched from the source branch. |
- AGENTS.md: clarify that .select() with fields.* requires .withContentType() first (client-side IllegalStateException, not an API error); sys-only selections have no such requirement - ARCHITECTURE.md: fix resolveLinks() description — it iterates entry content-type field definitions and looks up from the indexed maps, not "traverses the includes"; silently drops unresolved links - CONTRIBUTING.md: correct integration test setup — credentials are hardcoded in test classes, no env vars needed; clarify tests run locally only, not in CI - CONTRIBUTING.md: replace bare mvn with ./mvnw in release steps
Fix grammar typo in ADR 0006 (+ → and), correct logSensitiveData default in AGENTS.md (false → true, matching CDAClient.java line 583), and fix integration test CI claim in CONTRIBUTING.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Bito Automatic Review Skipped – PR Already Merged |
1 participant
Summary
Seeds the full Golden Context artifact set into
contentful.java— a pure-Java SDK for Contentful's Content Delivery and Preview APIs.Coverage: Before → After
README.mdARCHITECTURE.mdAGENTS.mdCONTRIBUTING.mddocs/ADRs/docs/specs/.gitkeep+ README.bito.yaml.bito/guidelines/Artifacts Created
ARCHITECTURE.md— System context diagram, internal package map, data flow through the post-processing pipeline (localize → map → raw fields → rich text → link resolution), key dependencies table with ADR cross-references, configuration reference, Android specifics, release and distribution details.AGENTS.md— Quick reference table, 13 sharp edges/invariants, key conventions, integration points, build verification loop.CONTRIBUTING.md(enriched) — Added: testing section, commit convention, branch strategy, release process with Maven commands, CI/CD table.README.md(enriched) — Added: "For Agents & Contributors" navigation table at bottom..bito.yaml— Comprehensive review mode, Bito guidelines enabled..bito/guidelines/review-posture.txt— SDK-specific review posture (public API contract, Android compat, post-processing pipeline focus)..bito/guidelines/repo-truth-and-boundaries.txt— Doc-grounded review rules, Java 8 / Android 21 target enforcement, ADR update requirements..bito/guidelines/domain-invariants.txt— Exhaustive invariants: post-processing pipeline order, link resolution behavior, public API contract, Android compatibility, sensitive data, TransformQuery, sync, cross-space, release.docs/specs/README.md— Scaffold with format guide.ADRs Generated
Redactions Applied (Public Repo)
ARCHITECTURE.md: Replaced "private key stored in 1Password" → "private key managed by Contentful infrastructure team"CONTRIBUTING.md: Replaced "stored in 1Password" → "obtain from your team lead"Flagged Items
Test Plan
./mvnw -B teststill passes in the devcontainer🤖 Generated with Claude Code
Summary by Bito
Seeds the full Golden Context artifact set into contentful.java — a pure-Java SDK for Contentful's Content Delivery and Preview APIs, adding comprehensive documentation and configuration for architecture, agents, contributions, ADRs, and automated review tools.
Detailed Changes