NO-JIRA: chore(docs/adr): document language preference for Python, Go, and TypeScript

[jiridanek]

• NO-JIRA: chore(docs/adr): begin recording architectural decisions made on this project with the help of adr-tools #858

Description

I fully admit this is less than half-baked at this point, but I believe the core idea of committing to use Python, Go, and TypeScript is already something we can discuss. The decision has been originally made back in Adriel's team, but we never wrote it down back then, besides in that Jira comment.

How Has This Been Tested?

Some time ago we abandoned skodjob/odh-e2e because it was written in Java and we decided not to do Java. That's the Jira I linked above.

Given the teams experience and preferences spreadsheet, Python, Go, and TypeScript seem reasonable choices.

Self checklist (all need to be checked):

• Ensure that you have run make test (gmake on macOS) before asking for review
• Changes to everything except Dockerfile.konflux files should be done in odh/notebooks and automatically synced to rhds/notebooks. For Konflux-specific changes, modify Dockerfile.konflux files directly in rhds/notebooks as these require special attention in the downstream repository and flow to the upcoming RHOAI release.

Merge criteria:

• The commits are squashed in a cohesive manner and have meaningful messages.
• Testing instructions have been added in the PR body (for PRs involving changes that are not immediately obvious).
• The developer has manually tested the changes and verified that the changes work

Summary by CodeRabbit

• Documentation
  • Added official architecture decision documentation that establishes strategic language preferences and development standards for future projects. Includes comprehensive decision rationale explaining the selection, practical migration guidance for transitioning existing systems and codebases to new standards, and detailed language-specific remarks with recommendations to support consistent implementation across all organizational development initiatives.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign caponetto for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Walkthrough

A new architecture decision document establishing language preferences (Python, Go, TypeScript over Bash) for new development. Document includes rationale, migration guidance, and language-specific considerations with metadata and standard ADR sections.

Changes

Cohort / File(s)	Change Summary
Architecture Decision Document docs/architecture/decisions/0003-prefer-python-go-and-typescript-in-this-order.md	New ADR document establishing language preferences (Python > Go > TypeScript) for future development, including context, decision rationale, consequences, migration guidance, and language-specific remarks

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Policy document addition with no code logic or functional changes
• Review focus: validate policy rationale, decision clarity, and migration guidance completeness

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Description Check	❓ Inconclusive	The pull request description follows the required template structure with sections for Description, How Has This Been Tested?, Self checklist, and Merge criteria. The author provides adequate context explaining the change (documenting a language preference decision for Python, Go, and TypeScript), references prior discussions and decisions, and provides historical rationale. However, the author explicitly states the work is "less than half-baked," which indicates acknowledged incompleteness, and two significant merge criteria items remain unchecked: testing instructions and manual testing verification. Additionally, the "How Has This Been Tested?" section provides rationale rather than concrete testing steps, though this may be acceptable for a documentation change. The combination of acknowledged incompleteness and unchecked merge criteria creates ambiguity about whether this PR is submitted as a complete proposal or as an early draft for discussion.	To resolve this, the author should clarify the PR's intent: if submitting for immediate merge, complete the unchecked merge criteria items (add testing instructions explaining how the ADR document was validated and confirm manual testing/verification). If this is an RFC or draft for discussion, the author should clearly label it as such. Additionally, the "How Has This Been Tested?" section should be expanded to explicitly describe what validation steps were taken, even if they differ from traditional code testing.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "NO-JIRA: chore(docs/adr): document language preference for Python, Go, and TypeScript" clearly and specifically describes the main change in the changeset. The title directly corresponds to the addition of a new architecture decision document that documents the language preference policy. The title is concise, specific enough for teammates to understand the primary change when scanning history, and contains no vague terms or unnecessary noise.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/architecture/decisions/0003-prefer-python-go-and-typescript-in-this-order.md (2)

1-1: Standardize capitalization to TypeScript (official brand).

The document uses both "Typescript" (lines 1, 19) and "TypeScript" (lines 42+). Standardize to the official brand spelling "TypeScript" throughout for consistency and correctness.

-# 3. Prefer Python, Go, and Typescript (in this order)
+# 3. Prefer Python, Go, and TypeScript (in this order)

-The team has agreed to use Python, Go, and Typescript, in this order.
+The team has agreed to use Python, Go, and TypeScript, in this order.

Also applies to: 19-19, 42-42

---

15-15: Simplify wordiness: replace "in preference to" with "over".

LanguageTool flags both instances of "in preference to" (lines 15 and 48) as potentially wordy. Consider using the more concise "over" instead.

-Use these languages in preference to Bash.
+Use these languages over Bash.

-We will consider using full-stack TypeScript in preference to having either a Python or Go backend to a TypeScript frontend.
+We will consider using full-stack TypeScript over Python or Go backends with a TypeScript frontend.

Also applies to: 48-48

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 731c89f and f16f705.

📒 Files selected for processing (1)

• docs/architecture/decisions/0003-prefer-python-go-and-typescript-in-this-order.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/architecture/decisions/0003-prefer-python-go-and-typescript-in-this-order.md

[style] ~15-~15: ‘in preference to’ might be wordy. Consider a shorter alternative.
Context: ...degree) TypeScript. Use these languages in preference to Bash. ## Decision The team has agreed...

(EN_WORDINESS_PREMIUM_IN_PREFERENCE_TO)

---

[style] ~48-~48: ‘in preference to’ might be wordy. Consider a shorter alternative.
Context: ...ll consider using full-stack TypeScript in preference to having either a Python or Go backend to...

(EN_WORDINESS_PREMIUM_IN_PREFERENCE_TO)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: pytest-tests
• GitHub Check: code-static-analysis

🔇 Additional comments (1)

docs/architecture/decisions/0003-prefer-python-go-and-typescript-in-this-order.md (1)

9-54: Document quality and structure are strong.

The ADR follows proper format with clear sections (Context, Decision, Consequences) and appropriate rationale for the language choices. The language-specific guidance (lines 26–48) provides helpful caveats and context—e.g., acknowledging Python's verbosity trade-off, Go's performance benefits, and TypeScript's web-native strengths. The narrow Bash scope (line 24) is pragmatic and clear.

Note: The PR checklist shows testing and manual verification unchecked; this is reasonable for a documentation-only change.