docs: Update README with up-to-date information

[jeanduplessis]

Completely rewrite README.md to align with open-source best practices:

• Add Key Features section highlighting Terraform execution modes
• Add "When to Use Upjet" guidance vs native providers
• Include architecture narrative with build-time vs runtime flow
• Expand provider list with accurate GitHub links
• Add comprehensive documentation table linking all guides
• Remove Quick Start (too complex for README scope)
• Update copyright year to 2026
• Improve descriptions and structure throughout

The README now provides clear value proposition, technical context, and proper navigation to detailed documentation.

Description of your changes

I have:

• Read and followed Upjet's contribution process.
• Run make reviewable to ensure this PR is ready for review.
• Added backport release-x.y labels to auto-backport this PR if necessary.

How has this code been tested

[jeanduplessis]

@CodeRabbit please review

[coderabbitai]

@jeanduplessis I'll review the README updates for you now!

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Warning

Rate limit exceeded

@jeanduplessis has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 18 minutes and 19 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

README.md fully rewritten and reorganized into a documentation-first layout: expanded product overview, Key Features, Architecture, Providers, Documentation table of contents, Contributing/Community, visuals (banner/overview), and license updates; primarily documentation changes only (no code/API changes).

Changes

Cohort / File(s)

Summary

Documentation Restructuring README.md

Complete rewrite and structural overhaul: replaced brief intro with comprehensive Upjet description; added banner and overview image; introduced Table of Contents and Documentation table; expanded Key Features, Architecture, Providers (major + additional), Contributing, Community, Prior Art; updated License text and copyright year; removed older external links and Getting Started; formatting and layout enhancements.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Would you like a concise changelog extracted or a focused review of any specific README subsection?

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change—a comprehensive README rewrite with updated information—and meets the 72-character limit requirement at 47 characters.
Description check	✅ Passed	The description is directly related to the changeset, providing specific details about README improvements including new sections, structural changes, and content updates.
Configuration Api Breaking Changes	✅ Passed	PR contains only README.md documentation updates with no changes to pkg/config source code or public API declarations.
Generated Code Manual Edits	✅ Passed	No generated code files matching 'zz_*.go' pattern have been modified. Only documentation, configuration, and workflow files were changed.
Template Breaking Changes	✅ Passed	The pull request contains only changes to README.md and does not modify any files in pkg/controller/external*.go, so no template changes affecting generated controller behavior are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

README.md (1)

133-153: Consider wrapping line 139 for consistency with the 100-character guideline.

The Contributing, Community, Prior Art, and License sections are well-organized and CONTRIBUTING.md is properly referenced. However, line 139 (the Slack community link) extends to 123 characters, which exceeds the 100-character wrapping guideline. Consider breaking this into two lines to maintain consistency:

- **Slack:** [#upjet](https://crossplane.slack.com/archives/C05T19TB729) on
  [Crossplane Slack](https://slack.crossplane.io)

This keeps the link definitions readable while respecting the formatting standards for the documentation.

🤖 Fix all issues with AI agents

In @README.md:
- Around line 106-119: Update the provider list entry that currently uses the
incorrect capitalization "Github" to the correct "GitHub" by editing the README
list item text (the line containing the "-
[Github](https://github.com/crossplane-contrib/provider-upjet-github)" entry);
leave the URL unchanged and only adjust the displayed link text to "GitHub".
- Around line 86-104: The README references an image at
docs/images/framework-overview.jpg that couldn't be found and two list lines
exceed the 100-char limit; confirm the image file exists in the repo or update
the path in the README to the correct location (or remove the image tag), and
wrap the long list entries (the lines for "3. Documentation Scraper - Extracts
and generates API documentation from Terraform docs" and "4. Migration Framework
- Supports migrating resources between provider versions") so each line is <=100
characters while preserving wording and list numbering.

📜 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 ad9ec82 and afd0e68.

⛔ Files ignored due to path filters (2)

• docs/images/framework-overview.jpg is excluded by !**/*.jpg and included by none
• docs/images/upjet-build-runtime.jpg is excluded by !**/*.jpg and included by none

📒 Files selected for processing (1)

• README.md

🧰 Additional context used

📓 Path-based instructions (1)

**/*.md

⚙️ CodeRabbit configuration file

**/*.md: Ensure Markdown files are wrapped at 100 columns for consistency and
readability. Lines can be longer if it makes links more readable, but
otherwise should wrap at 100 characters. Check for proper heading
structure, clear language, and that documentation is helpful for users.

Files:

• README.md

🪛 LanguageTool

README.md

[uncategorized] ~117-~117: The official name of this software platform is spelled with a capital “H”.
Context: ...grafana/crossplane-provider-grafana) - [Github](https://github.com/crossplane-contrib/...

(GITHUB)

🔍 Remote MCP

Summary of Relevant Context for PR Review

Based on my research, here is the additional context that would help effectively review this README update:

Project Context and Purpose

Upjet is a code generation framework and runtime for Crossplane providers. More specifically, the Crossplane steering committee voted to accept the donation of Upbound's provider framework (Upjet) as well as key Crossplane providers for the major cloud providers, making it a foundational component of the Crossplane ecosystem. Upjet automates the creation of Crossplane providers based on existing Terraform providers by transforming Terraform provider schemas into Crossplane CRDs.

Technology Evolution and Capabilities

Upjet is the second generation approach that is more stable, has more customization points, and includes new code generators that enable automatically generating API documentation and example YAMLs. Upbound's engineering team made a breakthrough to improve the overall efficiency of Upjet-based providers significantly, bringing faster provisioning and reconciliation of resources while reducing running costs.

Project Maturity and Governance

Upbound donated their entire Upjet provider framework to the Crossplane project, with this technology making the move from being a vendor-driven project to being completely owned and driven by the CNCF and Crossplane community. Upjet and the providers it generates use the permissive Apache 2 license.

Community and Documentation Resources

The project has comprehensive documentation available, including guides on generating a Crossplane provider based on an existing Terraform provider using Upjet, using the Terraform GitHub provider as an example. The README update aligns with the project's emphasis on clear documentation and navigation, which the PR accomplishes through the new documentation table and structured sections.

[::web_search::]

🔇 Additional comments (6)

README.md (6)

1-18: LGTM! Clean header and badges.

The copyright update to 2026 is appropriate, and the badge section is well-formatted. The badge links exceed 100 characters, but this is acceptable per the coding guidelines for improving link readability.

---

32-42: Excellent Table of Contents!

The TOC is comprehensive and well-organized, providing clear navigation to all major sections.

---

44-68: Great feature breakdown!

The Key Features section effectively highlights Upjet's capabilities with appropriate technical detail. The three-tier approach to Terraform execution modes (CLI, SDK v2, Framework) is particularly valuable information for users.

---

70-84: Valuable guidance for users!

This section provides balanced, practical advice that will help users make informed decisions. Thank you for including scenarios where a native provider might be more appropriate—this shows project maturity and user-focused thinking.

---

121-131: Great documentation table with correct file paths!

The documentation table provides excellent navigation for new contributors. All referenced documentation files exist and are properly linked. The table structure is clean and easy to follow.

---

20-29: Overview section is clear—let's verify a couple of details.

The overview effectively communicates Upjet's purpose and value proposition. Before merging, could you help verify:

1. The image path docs/images/upjet-build-runtime.jpg is correct and the file exists in the repository
2. The claim of "50+ community providers" is current—could you point to where this count comes from or any documentation that tracks these providers?

These small clarifications will help ensure the README is accurate and maintainable going forward.

[ulucinar]

Thank you @jeanduplessis for pulling this together. A few minor nits, happy to merge as is.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 20-25: Update the README text that currently claims "50+ community
providers": either verify that number against an authoritative source (e.g.,
provider registry or project maintainers) and add a parenthetical citation or
link, or replace the exact count with a non-stale phrase like "dozens of
community providers" (modify the sentence containing "50+ community providers")
so the statement remains accurate without requiring frequent updates; ensure the
chosen change appears where the phrase "50+ community providers" is used.

🧹 Nitpick comments (1)

README.md (1)

52-52: Wrap long bullet to meet 100‑column guideline.

Line 52 looks longer than 100 characters and isn’t link-driven. Could we wrap it for consistency with the doc style guide?

💡 Suggested wrap

-  - *Terraform Plugin Framework*: Protocol-based communication via protov6 (no-CLI invocation)
+  - *Terraform Plugin Framework*: Protocol-based communication via protov6
+    (no-CLI invocation)

[jeanduplessis]

Thank you for the valuable feedback @ulucinar to make this more technically accurate. I've incorporated all your feedback.