Merge branch 'docs/contributor-research'

Author: PreAgile

docs/contributor-research/README.md

@@ -0,0 +1,387 @@
+# Testcontainers Java Contribution Research
+
+## Goal
+
+This note summarizes contribution candidates for a Spring / Java / Kotlin backend engineer targeting `testcontainers/testcontainers-java`.
+
+The focus is not only "what is easy", but "what will look strong to backend hiring teams while still having a realistic merge path".
+
+## Repository Health
+
+- Upstream repository: `testcontainers/testcontainers-java`
+- Local fork remote: `PreAgile/testcontainers-java`
+- Current local branch: `main`
+- Working tree state at review time: clean
+
+Signals that the repository is actively maintained:
+
+- `good first issue` labels are still in use
+- merged PRs exist in late 2025 and early 2026
+- recent human-merged PRs include:
+  - `#11498` merged on `2026-02-26`
+  - `#11223` merged on `2026-03-02`
+
+## Local Codebase Areas That Matter
+
+Relevant local paths:
+
+- `docs/contributing.md`
+- `docs/contributing_docs.md`
+- `docs/modules/k6.md`
+- `modules/k6/src/test/java/org/testcontainers/k6/K6ContainerTests.java`
+- `modules/r2dbc/src/main/java/org/testcontainers/r2dbc/R2DBCDatabaseContainer.java`
+- `modules/postgresql/src/main/java/org/testcontainers/postgresql/PostgreSQLR2DBCDatabaseContainer.java`
+- `modules/mysql/src/main/java/org/testcontainers/mysql/MySQLR2DBCDatabaseContainer.java`
+- `modules/mongodb/src/main/java/org/testcontainers/mongodb/MongoDBContainer.java`
+- `modules/jdbc/src/main/java/org/testcontainers/jdbc/ContainerDatabaseDriver.java`
+
+## Maintainer Preference Pattern
+
+Observed pattern from recent merged PRs:
+
+- small scope
+- module-focused changes
+- tests included for code changes
+- low review burden
+
+Examples:
+
+- `#11498` changed 2 files and added a focused implementation plus test update
+- `#11223` changed 3 files with a targeted compatibility fix
+
+This strongly suggests that a first PR should avoid broad cross-cutting core changes.
+
+## Candidate Ranking
+
+### 1. Best first PR: `#8780`
+
+Title:
+
+- `[Enhancement]: Add example test to the K6 module docs`
+
+Why this is the safest first merge:
+
+- issue scope is clear
+- user pain is already documented in the issue body
+- implementation is mostly docs/example work
+- it does not require design negotiation across multiple modules
+
+Problem analysis:
+
+- `docs/modules/k6.md` currently includes a code snippet from `K6ContainerTests`
+- the docs show the API, but do not clearly present the "typical test shape" that users expect
+- the issue author explicitly compared it unfavorably to quickstart-style docs
+
+Root cause:
+
+- documentation exposes a snippet, but not an opinionated onboarding flow
+- discoverability is weaker than in other Testcontainers modules
+
+Why this helps a Spring/backend profile:
+
+- not as strong as a code PR, but excellent as a first merged foothold
+- shows you can read the repo conventions and contribute cleanly
+
+Recommended PR shape:
+
+- keep it to docs and possibly example snippet framing
+- do not over-design a new example project unless maintainers ask for it
+- align the K6 docs with the style of existing quickstart/test integration pages
+
+Merge probability:
+
+- high
+
+### 2. Best second PR: `#8797`
+
+Title:
+
+- `Add getR2dbcUrl helper method to JdbcDatabaseContainer`
+
+Why this is the best backend-signaling PR:
+
+- directly relevant to Spring, reactive stacks, database integration, and developer ergonomics
+- stronger hiring signal than a docs PR
+- maintainers already discussed acceptable design direction
+
+Problem analysis:
+
+- current R2DBC support exposes `getOptions(container)` methods
+- users who want a concrete R2DBC URL string must construct it manually
+- that hurts discoverability and ease of use
+
+Important maintainer guidance already found in the issue:
+
+- do not force this into a generic `JdbcDatabaseContainer` API immediately
+- preferred direction is static `getR2dbcUrl(container)` helpers on each `R2DBCDatabaseContainer` implementation
+- this was discussed explicitly by maintainers in the issue thread
+
+Existing failed attempt:
+
+- PR `#9569` attempted the feature
+- maintainer immediately asked for tests
+- contributor then got stuck on MSSQL-specific test issues
+- PR was eventually closed
+
+What that means:
+
+- the feature itself is not rejected
+- the implementation failed because the scope was too broad and the testing path got messy
+
+Best way to revive it:
+
+- comment on the issue first
+- confirm that the agreed static-method design is still welcome
+- explicitly propose a narrow first step
+- avoid broad "support everything at once" unless maintainers request it
+
+Safer implementation plan:
+
+1. Start with the stable implementations that are easiest to test cleanly
+2. Add tests alongside each helper
+3. Leave tricky drivers such as MSSQL for follow-up if needed
+
+Why this helps a Spring/backend profile:
+
+- strongest fit for Spring / Java backend positioning
+- good talking point for R2DBC, developer experience, and integration testing
+
+Merge probability:
+
+- medium to high if kept narrow
+- medium or lower if implemented across too many drivers at once
+
+### 3. High-value but risky: `#3066`
+
+Title:
+
+- `Support init scripts for MongoDBContainer without manually customizing the WaitStrategy`
+
+Why it is attractive:
+
+- strong backend signal
+- involves lifecycle, initialization order, replica set handling, and wait strategy design
+
+Problem analysis from issue and code:
+
+- placing scripts under `/docker-entrypoint-initdb.d` can trigger MongoDB restart behavior
+- local `MongoDBContainer` currently relies on `Wait.forLogMessage("(?i).*waiting for connections.*", 1)`
+- that does not robustly cover the init-script + replica-set startup sequence
+
+Root cause:
+
+- container readiness assumptions do not fully match Mongo init script behavior
+- `MongoDBContainer` also performs replica set initialization after start, which increases timing sensitivity
+
+Why it is risky as a first PR:
+
+- more design ambiguity
+- more regression risk
+- higher chance of maintainers asking for a reproducer-heavy discussion or broader design changes
+
+Merge probability:
+
+- medium at best for a newcomer first PR
+
+### 4. Not recommended first: `#1537`
+
+Title:
+
+- `Support hikari data-source-properties in ContainerDatabaseDriver`
+
+Why it looks easy but is not:
+
+- the surface request is "just pass `Properties info` through"
+- in practice it may affect:
+  - JDBC property propagation
+  - connection creation semantics
+  - cache key behavior in `ContainerDatabaseDriver`
+
+Root cause:
+
+- `ContainerDatabaseDriver.connect(String url, Properties info)` does not currently flow those properties in a newcomer-safe way
+- any fix in this path touches JDBC core behavior, not just one module
+
+Why it is a poor first PR:
+
+- too core
+- too broad
+- too easy to create subtle regressions
+
+Merge probability:
+
+- low for a first contribution
+
+## Recommended Order
+
+1. `#8780` K6 docs/example PR
+2. `#8797` R2DBC helper PR
+3. `#3066` MongoDB wait-strategy/init-script PR
+
+## First PR Recommendation
+
+### Recommended first merged PR
+
+Issue:
+
+- `#8780` `[Enhancement]: Add example test to the K6 module docs`
+
+Link:
+
+- `https://github.com/testcontainers/testcontainers-java/issues/8780`
+
+Why this is the best first PR:
+
+- the issue scope is concrete
+- the user pain is already written clearly in the issue
+- it avoids deep design arguments
+- it matches the small-PR preference observed in recent merged work
+
+Problem analysis:
+
+- `docs/modules/k6.md` already exposes API usage through codeinclude
+- however, it still does not clearly show the "expected JUnit-style test shape" that users look for
+- the issue reporter explicitly compared the docs to quickstart-style guidance and found the current page harder to follow
+
+Root cause:
+
+- the docs expose a runnable snippet
+- but the onboarding flow is weaker than in more polished Testcontainers pages
+- the page answers "what API exists" better than "how should I write my first test"
+
+Recommended solution shape:
+
+1. Update `docs/modules/k6.md`
+2. Reuse the existing runnable snippet from `modules/k6/src/test/java/org/testcontainers/k6/K6ContainerTests.java`
+3. Add a short JUnit-style explanation section
+4. Keep the change limited to docs and snippet framing unless maintainers request more
+
+Why this should merge well:
+
+- it is easy to review
+- it improves user onboarding directly
+- it does not expand the public API
+- it does not create cross-module risk
+
+Estimated merge probability:
+
+- high, assuming the PR stays small and aligned with existing docs conventions
+
+## Maintainer Interaction Strategy
+
+### Who is most likely to matter
+
+Based on issue and PR review activity observed during research:
+
+- `eddumelendez`
+- `kiview`
+
+This does not mean directly targeting them personally. It means:
+
+- write the issue comment in a way that makes review easy for maintainers who already triage this area
+- keep scope explicit
+- make it obvious that the change is intentionally narrow
+
+### Best way to approach `#8780`
+
+Suggested issue comment:
+
+> I’d like to work on this.  
+> My plan is to improve the K6 docs by adding a clearer JUnit-style example section based on the existing module test, while keeping the change small and aligned with the current docs/codeinclude style.
+
+This is strong because:
+
+- it signals ownership
+- it shows you read the existing docs structure
+- it reduces reviewer uncertainty
+
+### Best PR description style for `#8780`
+
+Suggested PR structure:
+
+```md
+## Summary
+Improve the K6 module documentation with a clearer JUnit-style example test.
+
+## Problem
+The current docs show the API usage, but it is still hard to understand the expected test structure quickly.
+
+## Changes
+- add a clearer example section to the K6 docs
+- reuse the existing runnable test snippet
+- keep the documentation aligned with the current codeinclude style
+
+## Why
+This makes the module easier to adopt for users looking for a quickstart-like testing example.
+```
+
+## Second PR Recommendation
+
+### Best first code PR after the docs PR
+
+Issue:
+
+- `#8797` `Add getR2dbcUrl helper method to JdbcDatabaseContainer`
+
+Link:
+
+- `https://github.com/testcontainers/testcontainers-java/issues/8797`
+
+Why this is the strongest backend-signaling follow-up:
+
+- aligns closely with Spring / reactive database usage
+- gives a better hiring signal than docs-only work
+- maintainers already discussed an acceptable design direction
+
+Important caution:
+
+- a previous attempt, PR `#9569`, was closed
+- the feature was not rejected
+- the attempt appears to have become too broad and got stuck in tests, especially around MSSQL
+
+Best way to revive it:
+
+Suggested issue comment:
+
+> I’d like to revive this using the static `getR2dbcUrl(container)` approach discussed above.  
+> To keep the scope reviewable, I plan to start with the stable implementations first and include tests for each one, leaving any problematic driver-specific follow-up for a separate PR if needed.  
+> Does that still match the expected direction?
+
+Why this approach should improve merge odds:
+
+- it respects prior maintainer discussion
+- it shows you learned from the closed PR
+- it reduces fear of a large cross-driver change
+
+## Suggested PR Positioning
+
+### For `#8780`
+
+PR message should emphasize:
+
+- clearer onboarding
+- quickstart-style discoverability
+- alignment with existing docs conventions
+
+### For `#8797`
+
+PR message should emphasize:
+
+- narrowed scope
+- implementation following the already discussed issue design
+- tests added for each touched helper
+- no attempt to redesign the entire R2DBC abstraction
+
+Suggested issue comment before coding:
+
+> I would like to revive this using the static `getR2dbcUrl(container)` approach discussed above.  
+> To keep the scope reviewable, I plan to add the helper with tests for the stable implementations first and leave any problematic drivers for a follow-up PR if needed.  
+> Does that still match the expected direction?
+
+## Practical Notes
+
+- For docs contributions, follow `docs/contributing_docs.md`
+- For code contributions, follow `docs/contributing.md`
+- Run formatting and tests before opening a PR
+- Keep each PR scoped to one issue and one clear problem
+- For a newcomer, "small and mergeable" is more valuable than "ambitious but stalled"