From Hello World to Core Contributor: Your Path Into Quarkus

How to get started, where to find good issues, and how to grow as a Java developer in a modern open-source project.

Quarkus is the Cloud-Native Java stack tailored for OpenJDK HotSpot and GraalVM, crafted from the best-of-breed Java libraries and standards. Its rapid growth and adoption are partly fueled by a vibrant open-source community. If you're using Quarkus, benefiting from its speed and efficiency, or simply interested in modern Java development, contributing back is a great way to improve the technology, enhance your skills, and gain visibility.

This article provides a pragmatic guide for Java developers and software architects on how to effectively contribute to the Quarkus project. I'll cover various contribution types, from documentation updates to core framework enhancements, catering to different experience levels.

Why Contribute to Quarkus?

Contributing to an open-source project like Quarkus offers several direct benefits:

1. Deepen Your Understanding: Working on the internals of Quarkus, its extensions, or documentation forces you to learn the framework at a much deeper level than simply using it.

2. Improve the Tool You Use: Your contributions directly enhance the framework, potentially fixing bugs that affect you or adding features you need.

3. Enhance Your Skills: You'll gain experience with cutting-edge Java development, build systems, testing practices, concurrent programming, GraalVM native image compilation, and collaborating on a large codebase using Git and GitHub.

4. Build Your Profile: Active contributions are visible on your GitHub profile, serving as a public portfolio of your skills and initiative.

5. Network with Experts: You'll interact with the core Quarkus team and other experienced developers in the community through mailing lists, chat, and pull request reviews.

6. Influence the Future: By participating in discussions and contributing code, you can help shape the direction of Quarkus.

Getting Started: Prerequisites

Before you jump into writing code or documentation, ensure you have the basic setup and understanding:

1. Core Tools:

   • Git: Essential for version control. You'll need a GitHub account.

   • JDK: A recent Java Development Kit (check Quarkus documentation for currently recommended versions).

   • Maven: Quarkus uses Maven as its primary build tool. Ensure it's installed and configured.

   • IDE: Your preferred Java Integrated Development Environment (IntelliJ IDEA, Eclipse, VS Code with Java extensions).

2. Quarkus Basics: Have a foundational understanding of Quarkus concepts – what it is, its main goals (developer joy, cloud-native, native compilation), and how basic applications are structured.

3. Communication Channels:

   • quarkus-dev Google Group: The primary mailing list for development discussions, major announcements, and proposing significant changes. Subscribe and observe discussions.

   • Quarkus Chat (Zulip): For more informal discussions, asking questions, and quick feedback. Join the relevant streams (e.g., #dev, #documentation).

   • Quarkus GitHub Discussions: Here you can discuss (almost) any topic around Quarkus community!

4. Project Repositories: Familiarize yourself with the main repositories:

   • quarkusio/quarkus: The core framework and extensions.

   • quarkusio/quarkus-quickstarts: Example applications.

   • quarkusio/quarkusio.github.io: The source for the quarkus.io website and documentation.

Finding Something to Work On

The Quarkus project is large, but finding a suitable task is manageable:

1. GitHub Issues: This is the central place for tracking bugs, feature requests, and tasks.

   • good first issue label: Look for issues tagged with good first issue. These are specifically selected as suitable entry points for new contributors.

   • help wanted label: These issues might be slightly more complex but are tasks the core team would appreciate community help with.

   • area/* labels: Filter issues by specific areas (e.g., area/hibernate, area/resteasy-reactive, area/docs) if you have expertise or interest in a particular component.

2. Review Documentation: Read through the guides on quarkus.io. If you find something unclear, incorrect, or missing, that's a potential documentation contribution. File issues and fixes!

3. Address Bugs You Encounter: If you find a bug while using Quarkus, first search existing issues. If it's not reported, create a detailed bug report. If you have the time and skills, you can then try to fix it yourself.

4. Ask on Communication Channels: If you have an idea for an improvement or a new feature (especially a new extension), discuss it on the quarkus-dev mailing list or Zulip first to get feedback and ensure it aligns with the project's direction.

Types of Contributions

Contributions can range from minor text edits to substantial new features. Here are the common types:

1. Documentation Improvements

Clear, accurate, and comprehensive documentation is crucial for any framework. This is often the easiest way to make your first contribution.

• What: Fixing typos, clarifying confusing sentences, adding missing information, improving examples, restructuring sections for better flow, creating new guides.

• How:

  • Documentation lives in the quarkusio/quarkusio.github.io repository.

  • Follow the standard GitHub Fork & Pull Request workflow (detailed later).

  • Adhere to the AsciiDoc format used by the project.

  • Small fixes (typos, grammar) often don't require prior discussion. For larger changes (new guides, significant restructuring), briefly propose your idea on Zulip or the mailing list.

• Make sure you have reviewed the following Quarkus contributor resources:

  • The Documentation section of the Quarkus "Contributing" guide.

  • The Quarkus style and content guidelines for the required syntax, preferred style, and other conventions.

  • The Quarkus documentation content types.

  • You have the AsciiDoc syntax reference nearby.

2. Bug Fixes

Addressing bugs reported by you or others is a valuable code contribution.

• What: Fixing incorrect behavior, performance issues, or unexpected errors in the Quarkus core or existing extensions.

• How:

  • Find an existing bug report on GitHub Issues or create a new one if necessary. Provide clear steps to reproduce the issue.

  • If you intend to work on an issue, leave a comment indicating your intent (I'd like to work on this) to avoid duplicated effort.

  • Follow the Fork & Pull Request workflow on the quarkusio/quarkus repository.

  • Crucially, write a test case that reproduces the bug before you fix it, and ensure the test passes after your fix. This prevents regressions.

  • Reference the issue number in your Pull Request (e.g., Fixes #12345).

3. New Extensions

Creating new extensions integrates third-party libraries or provides new capabilities within the Quarkus ecosystem. This is a significant contribution requiring a good understanding of Quarkus's build-time augmentation process.

• What: Integrating a new library (e.g., a database driver, messaging client, cloud service SDK) or creating novel functionality leveraging Quarkus's architecture.

• How:

  • Read everything about how to write your own extension!

  • Validate the Idea: Before writing code, search for existing extensions and discuss your proposal on the quarkus-dev mailing list. Explain the library/feature and why it would be valuable as a Quarkus extension.

  • Development:

    • Use the Quarkus extension Maven archetype: mvn io.quarkus.platform:quarkus-maven-plugin:create-extension -DextensionId=my-extension-artifactId

    • Develop the runtime (runtime module) and deployment (deployment module) parts. The deployment module handles build-time processing (e.g., generating bytecode, registering beans, configuring native image).

    • Re-read the "Writing Your Own Extension" guide in the Quarkus documentation ;-)

  • Testing: Implement comprehensive tests, including unit tests, integration tests, and native mode tests (@QuarkusIntegrationTest).

  • Documentation: Write a clear guide explaining how to use your extension, including configuration properties. .

  • Submission: Make sure you extension has been published to Maven Central and you follow the guidelines available in the extension guide.

4. Core Quarkus Enhancements

Contributing directly to the core framework involves modifying the fundamental parts of Quarkus, such as the build system, dependency injection, configuration management, or native image support.

• What: Implementing new core features, refactoring existing core code for performance or maintainability, improving the build process.

• How:

  • These contributions typically require a deep understanding of Quarkus internals.

  • Discuss First: Propose significant core changes on the quarkus-dev mailing list before implementation. Provide a clear rationale and outline your proposed approach.

  • Follow the standard Fork & Pull Request workflow.

  • Include thorough tests and documentation updates.

  • Expect detailed code reviews due to the potential impact of core changes.

5. Blog Posts and Articles

Sharing your knowledge and experiences helps the community grow and learn.

• What: Writing tutorials, case studies, deep dives into specific features, or comparisons involving Quarkus.

• How:

  • Publish on your personal blog, company blog, or platforms like Medium or DZone.

  • Share your article on social media (mentioning @QuarkusIO on Twitter/X) and potentially in the Quarkus Zulip chat (#community stream).

  • For exceptionally high-quality or unique content, you might reach out to the core team via the mailing list to see if it's suitable for cross-posting on the official Quarkus blog.

6. Website Enhancements

Improving the main quarkus.io website.

• What: Fixing broken links, improving UI/UX, enhancing navigation, updating information (beyond the technical guides covered under Documentation).

• How:

  • The website source is in the quarkusio/quarkusio.github.io repository.

  • Follow the Fork & Pull Request workflow.

  • For significant UI changes, discuss them first via GitHub issues or Zulip.

The Contribution Workflow (Git & GitHub)

Most contributions follow this standard open-source workflow:

1. Fork: Create a personal copy (fork) of the relevant Quarkus repository (e.g., quarkusio/quarkus or quarkusio/quarkusio.github.io) on GitHub.

2. Clone: Clone your forked repository to your local machine:

git clone https://github.com/<your-username>/quarkus.git
cd quarkus

1. Configure Remotes: Add the original Quarkus repository as an upstream remote to fetch changes:

git remote add upstream https://github.com/quarkusio/quarkus.git

1. Sync: Keep your fork's main branch synchronized with the upstream repository:

git fetch upstream
git checkout main
git merge upstream/main
# Optional: push the updated main to your fork
# git push origin main

1. Branch: Create a new branch for your contribution. Use a descriptive name:

git checkout -b my-fix-or-feature-branch

1. Code & Test: Make your changes (code, documentation, etc.). Crucially, add or update tests. Run the relevant Maven build commands to ensure everything compiles and tests pass (e.g., mvn clean install -DskipTests followed by specific module tests, or mvn clean install for a full build if necessary).

2. Commit: Commit your changes with clear, concise commit messages. Reference the GitHub issue if applicable:

git add .
git commit -m "Fix: Resolve null pointer in REST client reactive #12345"
# Or for features:
# git commit -m "Feat: Add support for new XYZ protocol"
# Or for docs:
# git commit -m "Docs: Clarify configuration property for datasource"

1. Push: Push your branch to your fork on GitHub:

git push origin my-fix-or-feature-branch

1. Create Pull Request (PR): Go to your fork on GitHub. You should see a prompt to create a Pull Request from your new branch.

   • Ensure the base repository is quarkusio/quarkus (or relevant repo) and base branch is main.

   • Ensure the head repository is your fork and compare branch is my-fix-or-feature-branch.

   • Write a clear title and description for your PR. Explain what the PR does and why. Link to the relevant GitHub issue (e.g., Fixes #12345).

   • Ensure the "Allow edits by maintainers" checkbox is ticked.

2. Review & Iterate: Project maintainers will review your PR. They may ask questions or request changes. Respond to feedback promptly and push further commits to the same branch if needed – the PR will update automatically.

3. Merge: Once approved, a maintainer will merge your PR into the main codebase. Congratulations!

Code Style and Testing

• Code Style: Quarkus uses a standard Java code style, enforced via Eclipse code formatter.

• Testing: Contributions, especially code changes, must include tests. This includes unit tests (JUnit) and often integration tests (@QuarkusTest for JVM mode, @QuarkusIntegrationTest for native mode or JAR testing). Good test coverage is essential for maintaining project stability.

Communication is Key

Don't hesitate to ask questions! Use the quarkus-dev mailing list for broader design discussions or proposals, and Zulip chat for quicker questions or clarifications during development. It's better to ask early, especially before investing significant time in a complex feature or change.

Beyond Your First Contribution

After your first few contributions, you'll become more familiar with the codebase, processes, and community. Consistent, high-quality contributions can lead to:

• Increased Trust: Maintainers will recognize your name and potentially review your PRs faster.

• Tackling Complex Issues: You can take on more challenging bugs or features.

• Mentoring Others: Help new contributors get started.

• Potential Committership: Long-term, highly active contributors might be invited to become committers with more direct write access (though this is a significant commitment).

Contributing to Quarkus is rewarding

Contributing to Quarkus is a rewarding process that benefits both you and the wider Java community. Whether you're fixing a typo in the documentation, squashing a bug, or building a whole new extension, your efforts help make Quarkus a better framework. Start small, follow the guidelines, engage with the community, and don't be afraid to ask questions. The Quarkus project welcomes constructive contributions at all levels.