Skip to content

Commit b7758ca

Browse files
committed
docs: expand contributor strategy notes
1 parent 34babb0 commit b7758ca

File tree

1 file changed

+135
-0
lines changed

1 file changed

+135
-0
lines changed

docs/contributor-research/README.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,141 @@ Merge probability:
218218
2. `#8797` R2DBC helper PR
219219
3. `#3066` MongoDB wait-strategy/init-script PR
220220

221+
## First PR Recommendation
222+
223+
### Recommended first merged PR
224+
225+
Issue:
226+
227+
- `#8780` `[Enhancement]: Add example test to the K6 module docs`
228+
229+
Link:
230+
231+
- `https://github.com/testcontainers/testcontainers-java/issues/8780`
232+
233+
Why this is the best first PR:
234+
235+
- the issue scope is concrete
236+
- the user pain is already written clearly in the issue
237+
- it avoids deep design arguments
238+
- it matches the small-PR preference observed in recent merged work
239+
240+
Problem analysis:
241+
242+
- `docs/modules/k6.md` already exposes API usage through codeinclude
243+
- however, it still does not clearly show the "expected JUnit-style test shape" that users look for
244+
- the issue reporter explicitly compared the docs to quickstart-style guidance and found the current page harder to follow
245+
246+
Root cause:
247+
248+
- the docs expose a runnable snippet
249+
- but the onboarding flow is weaker than in more polished Testcontainers pages
250+
- the page answers "what API exists" better than "how should I write my first test"
251+
252+
Recommended solution shape:
253+
254+
1. Update `docs/modules/k6.md`
255+
2. Reuse the existing runnable snippet from `modules/k6/src/test/java/org/testcontainers/k6/K6ContainerTests.java`
256+
3. Add a short JUnit-style explanation section
257+
4. Keep the change limited to docs and snippet framing unless maintainers request more
258+
259+
Why this should merge well:
260+
261+
- it is easy to review
262+
- it improves user onboarding directly
263+
- it does not expand the public API
264+
- it does not create cross-module risk
265+
266+
Estimated merge probability:
267+
268+
- high, assuming the PR stays small and aligned with existing docs conventions
269+
270+
## Maintainer Interaction Strategy
271+
272+
### Who is most likely to matter
273+
274+
Based on issue and PR review activity observed during research:
275+
276+
- `eddumelendez`
277+
- `kiview`
278+
279+
This does not mean directly targeting them personally. It means:
280+
281+
- write the issue comment in a way that makes review easy for maintainers who already triage this area
282+
- keep scope explicit
283+
- make it obvious that the change is intentionally narrow
284+
285+
### Best way to approach `#8780`
286+
287+
Suggested issue comment:
288+
289+
> I’d like to work on this.
290+
> 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.
291+
292+
This is strong because:
293+
294+
- it signals ownership
295+
- it shows you read the existing docs structure
296+
- it reduces reviewer uncertainty
297+
298+
### Best PR description style for `#8780`
299+
300+
Suggested PR structure:
301+
302+
```md
303+
## Summary
304+
Improve the K6 module documentation with a clearer JUnit-style example test.
305+
306+
## Problem
307+
The current docs show the API usage, but it is still hard to understand the expected test structure quickly.
308+
309+
## Changes
310+
- add a clearer example section to the K6 docs
311+
- reuse the existing runnable test snippet
312+
- keep the documentation aligned with the current codeinclude style
313+
314+
## Why
315+
This makes the module easier to adopt for users looking for a quickstart-like testing example.
316+
```
317+
318+
## Second PR Recommendation
319+
320+
### Best first code PR after the docs PR
321+
322+
Issue:
323+
324+
- `#8797` `Add getR2dbcUrl helper method to JdbcDatabaseContainer`
325+
326+
Link:
327+
328+
- `https://github.com/testcontainers/testcontainers-java/issues/8797`
329+
330+
Why this is the strongest backend-signaling follow-up:
331+
332+
- aligns closely with Spring / reactive database usage
333+
- gives a better hiring signal than docs-only work
334+
- maintainers already discussed an acceptable design direction
335+
336+
Important caution:
337+
338+
- a previous attempt, PR `#9569`, was closed
339+
- the feature was not rejected
340+
- the attempt appears to have become too broad and got stuck in tests, especially around MSSQL
341+
342+
Best way to revive it:
343+
344+
Suggested issue comment:
345+
346+
> I’d like to revive this using the static `getR2dbcUrl(container)` approach discussed above.
347+
> 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.
348+
> Does that still match the expected direction?
349+
350+
Why this approach should improve merge odds:
351+
352+
- it respects prior maintainer discussion
353+
- it shows you learned from the closed PR
354+
- it reduces fear of a large cross-driver change
355+
221356
## Suggested PR Positioning
222357

223358
### For `#8780`

0 commit comments

Comments
 (0)