Contributing to Quarkus for the first time
Hacktoberfest has begun and Quarkus, as a lot of other Open Source projects, is a perfect place to make your contributions to fulfill this 4 PR challenge in meaningful way.
Today, Monday, at 6:30pm CEST, I will make a live stream on How to contribute to Quarkus for the first time on Quarkus Insights,
I will use the advice in the blog below in practice and create contributions live. If it’s of interest to you, come and join us, we’ll answer as much question as we can, the details are in this tweet.
Quarkus has a very welcoming community, we welcome contributions from everybody, and try to make our best to help people making contributions even if they are not familiar with it. So don’t be shy and reach out to us if you want to contribute!
How I got started
In this article, I will try to give you some tips to help you create your first contribution to Quarkus.
I was a new contributor myself some times ago you may wonder how I have started?
With small contributions: bugfixes and documentations of course!
Then I had the opportunity to meet Quarkus core members Emmanuel Bernard and Clement Escoffier at Devoxx France, and we had a long discussion on MongoDB followed by some email exchanges.
After this, I helped to test the Mongo Client extension (authored by Clément Escoffier).
All this leads to the creation of the MongoDB with Panache extension, a huge work of design, coding and re-coding, documentation, …
Creating this extension took me several weeks (even if the core development was done in a few days) so if you plan to make an extension, be prepared (the review itself took several weeks with more than 250 github comments).
This was challenging, exciting, enriching, … but if you plan to do the same be prepared to a long journey.
OK, now let’s see how to make your first contribution to Quarkus.
Setting things up
Before being able to contribute, you must fork the Quarkus repository and build it on you local computer, even if you plan to contribute in an other area of Quarkus (more information on this later), you must be able to build the main Quarkus repository.
Clone the repository : git clone https://github.com/<your-fork-repo>/quarkus.git then build Quarkus via mvn clean install -Dquickly.
The Maven command will launch a minimal build of Quarkus and install the dependencies locally.
If it didn’t work follow the CONTRIBUTING - Setup page to setup your environment, anyway at some point you may need to read this page!
If you’re new to Quarkus: read the guides in the getting started page, you can skip the native and reactive ones if you don’t plan to contribute on these areas, and as a new contributor I’ll advise you to avoid them!
You can read the CONTRIBUTING page for general guidelines, if you don’t understand everything don’t panic ;), or you can refer to it if needed as it can be hard to read for newcomers.
Then, the hardest part will begin, you will need to find what you plan to do as a contributor, you can make contributions in the following areas:
-
documentation
-
code : core, extension, devtools
-
integration test
-
quickstart
-
website
Or just tell us your story with Quarkus, we love to hear user stories, and have a dedicated page, and blog category #user-story for them.
We make our best to offer good first issue,
and you can ask as many questions as you want (none are stupid questions) in our Zulip dev channel.
We even setup a dedicated channel for Hacktoberfest: hackaton.
Working on something
When you’re decided to work on something, you can find help on Zulip or GitHub by pinging area maintainers.
If there is an issue already opened, ask that someone assign it to you (you can add a comment for this on the issue).
If you plan to work on new stuff, ask on Zulip or the mailing list before starting for all community to be aware of your plan.
If you want to create a new extension, congratulation! But you should definitely ask on the mailing list plus create an extension proposal on github. Extension contribution is a long process with a design phase, and a discussion phase prior to any implementation.
As a newcomer, better to make small contributions first, remember my personal story on the introduction …
Tips on contributing
Now it is time to give you some tips to facilitate your first contribution based on the different contribution type you can do.
Documentação
Quarkus documentation is based on guides that are located inside the docs/src/main/asciidoc of the Quarkus repository.
There is a separate Asciidoc file per guide. The name of the guide is the last part of the doc URL so they are easy to find.
After any documentation contribution, always build the guide via mvn clean package and test them!
The guides are generated as HTML so you can open them in a browser, be careful to always test the links as it’s the most common cause of documentation issues.
Integration Test
Quarkus integration tests are in the integration-tests directory of the Quarkus main repository.
There should be at least one test by extension plus the main one that tests together multiple extensions that are common on rest services: JAX-RS, Health, JPA, …
When you update a test, it’s better to launch it on both JVM mode using mvn clean test
and native mode using mvn clean integration-test -Pnative-image (the native profile can have a different name, check the pom.xml if needed).
If you didn’t setup native image compilation in your computer, you can let the CI run it for you in native.
If you plan to add a new integration test, ask for some advice as there will be some extra steps to take to configure the CI.
Code
The code is split into multiple parts, I didn’t contribute to all of them so I will only introduce the one I know the best, but they are also the easiest one to contribute so it should be enough to start with.
You will find the following areas:
-
core: this is the core runtime and deployment modules of Quarkus. Ask for help if you want to contribute in it.
-
devtools: where the Maven and Gradle plugins lies.
-
bom: where all libraries are managed. Be sure to build all the Quarkus relevant tests after updating a library.
-
extension: where all the extensions lies. An extension is an integration of a third party library or framework into Quarkus.
Most contributions are done inside the extensions, at least for new contributors, as the other area are harder to work on. It is best to read the Building my first extension guide to have an overview of how extensions works.
Extensions are split into two parts (and an optional third one):
-
deployment: code executed at build time. It should contain a build processor that execute build steps and generate build items. If you need to contribute to the deployment part of an extension be sure to read the extension author guide and to understand the extension philosophy section. Personally I love this old presentation Quarkus and GraalVM: booting Hibernate at supersonic speed, subatomic size by Sanne Grinovero that explains how Hibernate is integrated inside Quarkus, but there should be other contents that may explain the extension design.
-
spi: optional - allow to share some build items with some other extension deployment modules.
-
runtime: code executed at runtime. It includes the extension configuration, a recorder (records runtime deployment build steps to re-do them when you application starts), the user API if any, and all the code that allow to start the library/framework.
Each extension should have its integration test, if not, check if the extension is tested inside the main one. Be sure to launch the test before commmiting your changes.
Each extension has its guide, if you add a new functionality, document it there!
Before commiting, you must be sure that your code passes the formatting style and obey to the enforcer rules. The better way to do this is to install the extension locally via ̀`mvn clean install`.
Quickstart
The Quickstarts are located inside a separate repo, that has its own contributing guidelines.
Again, you need to fork it and work on your own fork.
Each extension should have its own quickstart, the link of the quickstart should be on the extension guide (but it’s not always the case).
The quickstart must reflect as much as possible the code described inside the extension guide, so don’t contribute something inside it that didn’t reflect the guide.
As always, before pushing your changes: test and install it locally!
The Website
The website is located in a separate repo, that has its own contributing guidelines.
I only contributed once to it and I didn’t remember any special tips that again, test and install it locally!
The guides are in the main Quarkus repo so don’t try to update one of them inside the website repository.
Creating a PR
Push to your fork after having reviewed locally your changes, tested them and installed the updated component locally.
Always wait for the github action on your own fork to end before opening a PR, a full CI run took hours so better to be sure it passes before
making it run on the Quarkus repo.
There is a small video that explain our CI and how to activate it in your fork.
Then, create a PR, and the review process will start ;)
There is a bot that tags the PRs and ping the maintainers of the area, if it didn’t tagged yours, you can wait a few hours for someone to notice it, or ping someone directly or reach out on Zulip or the mailing list.
Wrapup
This is a long post, and I hope it’ll help you contributing to Quarkus!
As I repeat it during this post: start small, test everything, ask for help. These are my best advices.
Today, Monday, at 6:30pm CEST, I will make a live stream on How to contribute to Quarkus for the first time on Quarkus Insights, I will take these advices in practice and create contributions in live. If it’s of interest to you, come and join us, we’ll answer as much question as we can, the details are in this tweet.
