Skip to content

docs(concepts): add PackageSource/Package architecture to Key Concepts#445

Merged
kvaps merged 1 commit intomainfrom
docs/package-source-architecture
Mar 11, 2026
Merged

docs(concepts): add PackageSource/Package architecture to Key Concepts#445
kvaps merged 1 commit intomainfrom
docs/package-source-architecture

Conversation

@IvanHunters
Copy link
Contributor

@IvanHunters IvanHunters commented Mar 10, 2026

Summary

  • Add PackageSource and Package CRD architecture documentation to the Key Concepts page
  • Cover the full application lifecycle: reconciliation flow, dependencies, update propagation, rollback strategies, and FluxPlunger auto-recovery
  • Document the cozypkg CLI tool for managing Package and PackageSource resources
  • Include Mermaid diagrams following existing project conventions

Test plan

  • Hugo builds without errors
  • All Mermaid diagrams render correctly at /docs/v1/guides/concepts/
  • Page structure and navigation work as expected
  • Content reads naturally as a reference page

@claude
docs(concepts): add PackageSource/Package architecture to Key Concepts
0feed82 
Add sections covering the full application lifecycle in Cozystack v1:
reconciliation flow, package dependencies, update propagation, rollback
strategies, FluxPlunger auto-recovery, and cozypkg CLI tool.

Co-Authored-By: Claude <[email protected]>
Signed-off-by: ohotnikov.ivan <[email protected]>
@netlify
Copy link

netlify bot commented Mar 10, 2026 •
edited
Loading

✅ Deploy Preview for cozystack ready!

Name Link
🔨 Latest commit 0feed82
🔍 Latest deploy log https://app.netlify.com/projects/cozystack/deploys/69b07c1058128e0007feacf2
😎 Deploy Preview https://deploy-preview-445--cozystack.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 10, 2026 •
edited
Loading

Warning

Rate limit exceeded

@IvanHunters has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 9 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.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5cc827ff-720c-48f8-8e2b-56b8f41d8e0f

📥 Commits

Reviewing files that changed from the base of the PR and between 2d43914 and 0feed82.

📒 Files selected for processing (1)
  • content/en/docs/v1/guides/concepts.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs/package-source-architecture

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

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

@gemini-code-assist
Copy link
Contributor

gemini-code-assist bot commented Mar 10, 2026

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Cozystack documentation by introducing a detailed explanation of the PackageSource and Package architecture. It clarifies how applications are managed from external registries to deployed Kubernetes resources, covering the entire lifecycle, including updates, rollbacks, and error recovery. Additionally, it provides comprehensive guidance on using the cozypkg CLI tool for interactive management of these resources, making the system more understandable and user-friendly.

Highlights

  • PackageSource and Package Architecture: Added comprehensive documentation for the PackageSource and Package CRDs, detailing their roles in the Cozystack application lifecycle.
  • Application Lifecycle: Documented the full application lifecycle, including reconciliation flow, dependency management, update propagation, various rollback strategies, and FluxPlunger's auto-recovery mechanism.
  • cozypkg CLI Tool: Introduced documentation for the cozypkg command-line interface, explaining its functionalities for managing Package and PackageSource resources, including installation, adding, listing, deleting, and visualizing dependencies.
  • Visualizations: Incorporated multiple Mermaid diagrams to visually explain complex concepts such as the reconciliation flow, dependency gating, update propagation, rollback strategies, FluxPlunger recovery, and cozypkg's interaction with the lifecycle.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog
  • content/en/docs/v1/guides/concepts.md
    • Updated the page description to include "PackageSource/Package lifecycle".
    • Added a new major section "PackageSource and Package" explaining the CRDs.
    • Detailed the "Reconciliation Flow" with a Mermaid diagram.
    • Explained "Package Dependencies" with a Mermaid diagram.
    • Described the "Update Flow" with a Mermaid diagram and CLI commands.
    • Outlined "Rollback Strategies" with three approaches and Mermaid diagrams.
    • Documented "FluxPlunger Auto-Recovery" with a Mermaid diagram.
    • Provided a "Lifecycle Operations Summary" table.
    • Added a new major section "cozypkg CLI" covering its purpose, installation, and commands (add, list, del, dot).
    • Included a Mermaid diagram illustrating "How cozypkg Fits into the Lifecycle".
Activity
  • No specific activity has been recorded for this pull request yet.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

@IvanHunters IvanHunters marked this pull request as ready for review March 10, 2026 20:17
gemini-code-assist[bot]
gemini-code-assist bot reviewed Mar 10, 2026
View reviewed changes
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds extensive documentation for PackageSource and Package concepts, including their lifecycle, management with cozypkg, and various operational flows. The documentation is well-structured and comprehensive. I have one minor suggestion to improve the readability of code blocks by specifying the language for syntax highlighting.

Note: Security Review has been skipped due to the limited scope of the PR.

content/en/docs/v1/guides/concepts.md

To speed up synchronization without waiting for the next polling interval (Flux sources live in the `cozy-system` namespace):

```text
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For better readability through syntax highlighting, it's recommended to specify the language for code blocks containing shell commands. You can use sh or bash instead of text. For example, change this line to ```sh.

This suggestion applies to other blocks in this document that contain shell commands.

kvaps
kvaps approved these changes Mar 11, 2026
View reviewed changes
Copy link
Member

@kvaps kvaps left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@kvaps kvaps merged commit 6e3dcc4 into main Mar 11, 2026
6 checks passed
@kvaps kvaps deleted the docs/package-source-architecture branch March 11, 2026 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kvaps kvaps kvaps approved these changes

@lllamnyp lllamnyp Awaiting requested review from lllamnyp lllamnyp is a code owner

+1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@IvanHunters @kvaps