Welcome! We're so glad you're here and interested in contributing to Flatcar! 💖

• Contributing Guide
  • Table of Contents
  • Ways to Contribute
  • Getting Started
    • Finding Issues
    • Proposing New Features
  • Repository Overview
    • OS Image Build System
    • Update and Reboot Infrastructure
    • Node Configuration and Provisioning
    • System Extensions
    • Testing and Tooling
    • Deployment and Cloud
    • Cluster API Integration
    • Flatcar Apps
    • Project and Community
  • Communication Channels
  • Development
    • Development Environment Setup
    • Pull Request Lifecycle
    • Authoring PRs
      • Commit Best Practices
      • PR Description
    • Commit Guidelines
      • The Rules
      • Examples

As a newcomer, you're actually in the best position to help us improve! We'd really love your feedback on:

• Confusing steps when setting up your developer environment
• Missing information in our guides or documentation
• Bugs or rough edges in our automation scripts

If something doesn't make sense or doesn't work, please let us know by opening a bug report — we genuinely appreciate it and every bit of feedback helps make Flatcar better!

There are so many ways to get involved! We welcome all kinds of contributions:

Not everything happens through a GitHub pull request. Please come to our meetings or contact us to discuss how we can work together — we'd love to meet you!

Thinking of contributing? Awesome! The best way to start is to engage with the project early — drop a comment on an existing issue or open a new one. Let us know what you're interested in working on. This helps us help you, and it's often the key to getting your contribution accepted smoothly.

To report bugs or request features, just file an issue — we're always happy to help point you in the right direction!

Not sure where to start? No worries — we've got you covered!

💡 Tip: Don't see any issues with these labels? No problem! There's always something exciting to work on. Hop on Discord or join one of our Office Hours — we'll find something that fits your interests and skill level.

🌟 Great for newcomers: Consider contributing a Flatcar App! A Flatcar App is a reference implementation showing how to run a specific service on Flatcar (e.g., Minecraft Server, Jitsi). It's a fantastic way to learn Flatcar hands-on while creating something awesome that helps other newcomers learn too!

Found something you'd like to work on? Excellent! Just leave a comment like "I'd like to work on this" — that's all it takes to claim it.

Got an idea for a new feature or a big architectural change? We'd love to hear it! Don't be shy — the best approach is to open an issue first so we can discuss it together before you invest time in implementation.

For package requests, use the "New Package Request" issue type and check out Adding New Packages for guidelines.

The Flatcar project is spread across multiple repositories in the flatcar GitHub organisation. Here is a map of the key repos, grouped by function, to help you find where to contribute.

These repos are the beating heart of the OS image build system.

Flatcar ships atomic, automatic updates. These repos implement the full update and reboot-coordination stack.

Tools for bootstrapping and configuring nodes at first boot.

Flatcar is minimal by design; system extensions let you layer software on top without modifying the read-only OS image.

Templates, examples, and tooling for getting Flatcar running on cloud and on-prem infrastructure.

Reference implementations showing how to run real-world services on Flatcar — great for learning and as starting points for your own deployments.

💡 Starting out? scripts is where most OS-level contributions happen. sysext-bakery is a great low-barrier entry point for adding or updating software extensions.

For all communication channels, community meetings, and social media links, see the Communication Channels section in the README. Come hang out with us on Discord!

Ready to dive into the code? Let's go! Our Developer Guides will walk you through the Flatcar SDK and common tasks like adding or upgrading packages. Start here:

• Building Custom Images from Source

These guides will give you a solid foundation for working with the SDK and help you submit PRs that sail through review!

Pull requests can be issued from repository branches (maintainers only) or from forks. The project treats all PRs equally for review and merge, regardless of origin.

Requirements:

• Successful CI
• At least one LGTM from a maintainer who is not the PR author
• Approvers may be co-authors (allowing reviewers to suggest changes)

Stages:

💡 Tip: PR feeling stuck? Don't be shy — reach out on Discord or bring it up in a community meeting. We're here to help and we want to see your contribution succeed!

Here are some tips to make your PRs shine and get merged quickly:

• Atomic commits: Each commit should be self-contained and address a single logical change. See the Linux Kernel guide on separating changes.

• Meaningful messages: Commit messages should explain why something is done, not just what. See describing changes.

• Clean history: Use git rebase to squash and order commits logically. Don't retain messy development history.

• No throwaway commits: Don't add code you'll change in a later commit. Squash related changes together.

• Self-review: Give your own code a critical look before submitting — you'll often spot things you missed, and reviewers will thank you!

Think of your PR description as a cover letter. Help reviewers understand:

• Explain why you're proposing the change
• Provide an overview of the changes
• List any unresolved questions or TODO items
• Give reviewers the context they need

Great commit messages make everyone's life easier (and make you look like a pro!). Here's the format we use:

<area>: <description of changes>

Detailed information about the commit message goes here.

✅ Good:

app-shells/bash: update ebuild to 5.3

Gentoo upstream has unmasked bash 5.3 and declared it stable.
This change updates the component to use the latest upstream ebuild.

❌ Bad:

Update bash

Updated bash to the latest one.

Thanks for reading, and thank you so much for contributing! 🙏 We're thrilled to have you as part of the Flatcar community. If you have any questions at all, don't hesitate to reach out — we're always happy to help and can't wait to see what you build! 🎉