Contribute to the Astro's project

I’ve been using open-source projects for a long time, but I’ve never really contributed to an existing project. I’ve created a few issues or fixed one or two minor bugs or typo in the documentation, but I’ve never tried to get involved.

Then, in 2024, I finally found a project that made me want to participate. This project is called Astro! A year later, I share with you my journey and some ideas if you also want to get started.

What is a contribution?

Before I venture further, I think it’s important to define what I mean by contribution. For many, participating in an open-source project is synonymous with coding. Sure, coding is a valuable skill that’s applicable to all projects, but there are other ways to contribute.

In my opinion, any act that helps to evolve a project can be called a contribution:

• Are you experiencing a bug? Create a detailed ticket with a minimal reproduction so that it can be fixed and does not happen to other people!
• Do you know how to fix a bug? Feel free to create a “pull request” (or “merge request” depending on the platform)!
• Are you more comfortable with words? Consider looking at what can be done on the documentation!
• Are you fluent in English and another language? Feel free to see if you can help translate the documentation!
• Not comfortable enough in English to translate? You can always review the translations submitted in your language and approve or suggest improvements!
• Have you always enjoyed getting answers to your help requests? You can do the same by providing technical support to other users!

Well, you get the idea! There are many ways to contribute to a project. All kinds of skills can be useful.

My journey as an Astro contributor

A year ago, I decided to test Astro. I’m experiencing a problem but can’t find the information in the documentation. Rather than opening an issue in the main repository of Astro, I’m looking to see if a similar issue has been reported before. It turns out that it has and that it’s not a bug. Since it seems that I’m not the only one experiencing this issue, I figure the documentation should make that clear.

Issues opening

I thus create my first issue in the Astro Docs repository. This issue didn’t get a response right away, but that didn’t stop me from creating other issues in the other repositories when I encountered an issue that looked like a bug to me.

It’s not always obvious at first which repository to report the issue to. It’s possible to do it in the main repository… but I prefer it when I post in the right place the first time. These issues allowed me to get familiar with different repositories of the project: the core, the docs, the compiler and the language tools.

I was surprised by the reception; it’s pretty rare that someone thanks me for creating an issue! In itself, it’s not important. As long as the problem is fixed, that’s all that matters. That said, I recognize that this kind of reception makes a difference, especially when you’re not sure if it’s a bug or the expected behavior.

Followed by pull requests

I then took the opportunity of an issue labeled “Good first issue” (meaning: newcomers are welcome) to make my first PR in Astro’s main repo! The goal was to convert a remark plugin to a rehype plugin.

In June, my first ticket (related to documentation) was close to being solved, all that was missing was a PR. So I took that opportunity to do it myself.

The various interactions with the Astro team and contributors made me want to continue contributing. So I looked at what could be within my capabilities.

Involved in Astro Docs

Since I was learning how to use Astro, I decided to linger in the Astro Docs repository.

French translations

The documentation wasn’t completely translated in French. So I tell myself that participating in the translation would be a great way to be more familiar with Astro concepts!

I started by updating some translations and creating some missing translations. I also reviewed translations submitted by other contributors.

Reviewing the English documentation

I was curious to see the process of building the documentation as a whole. At the same time, Astro version 5 was appearing as a beta. So I started looking at other PRs and tickets, this time in English.

I was certainly less comfortable reviewing the English wording, but I was able to make myself useful by fixing any typos or formatting issues.

Various documentation improvements

While translating in French, I sometimes noticed some typos or formatting issues in the original version; this was a good opportunity to get a foot in the English documentation by correcting them.

Then I decided to make some improvements to the API Reference page. The idea was to bring a bit more consistency, add missing information and fix any errors. This gave me the opportunity to exchange with another member of the team.

When v5 was still in beta, I finally tested the Astro tutorial! A bit late… but there was no question of learning here. I wanted to help verify that everything was working correctly and make changes where necessary. I must say that it covers the concepts necessary to quickly get started with Astro!

Participating to the “Talking & Doc’ing” event

Every Thursday, or almost, a “Talking & Doc’ing” event is organized on the Astro’s Discord server. The idea behind this event is to discuss the best way to handle certain issues, changes to be made to a current PR, changes to the organization of the documentation, etc. Since I was interested in the process of creating the documentation, I finally decided to attend.

Since then, I continue to attend to this event. I say “attend” rather than “participate” because I must admit that I am rather passive. To begin with, I don’t really like speaking even in French (which can contrast with my writing). Then, as much as I can write in English, I am not particularly comfortable speaking in English. So, I leave my webcam (for the microphone) put away and I intervene only in writing. I must admit, it is not practical especially when it comes to discussing a PR created by oneself… Maybe one day I will decide to intervene orally.

A bit of technical support

I would sometimes answer questions about Astro on StackOverFlow. Then, when I started translating the Astro documentation, I joined Discord so I could coordinate with other translators and avoid having to submit a duplicate translation. I then started to intervene occasionally in the support channel.

Besides that, I try to help sort issues from the docs repository and from time to time, those from the core repository. If I see an issue that has already been addressed, it’s an opportunity to propose a solution or refer to a ticket that already covers that case.

Contributions leading to surprises

In December 2024, Astro 5 finally becomes stable. A blog post accompanies its official release. I already knew the different changes brought but I still read it with attention. Surprise at the bottom of the page: I saw my name in the acknowledgments!

Then, at the beginning of this year, I received a direct message on Discord from the co-founder of Astro. He offered me to join the Astro maintainers team. I wasn’t expecting it. I’ve certainly been quite active since June, but I didn’t think I would be trusted enough for this role and so quickly. Of course, I accepted this opportunity and I thank the team again for this trust!

Let’s take stock

I’m not going to hide it from you, yes, I found it a bit intimidating. To begin with, I’m more of an introvert and I’m not particularly comfortable communicating in English. Then, not being used to participating in open-source projects, I wondered if I was doing the right thing by intervening a bit everywhere (and especially in the Astro team’s PRs) or if it was too much…

That said, I don’t regret having started and getting involved in this project. I have to say that the welcome within the Astro community is no stranger to that. I have no doubt that there are other welcoming projects out there, but, I don’t know, there’s a little something extra. So, I’m glad I stumbled upon this project and to be part of it!

For now, I plan to stay on the documentation side even though I know it pretty well now. There are always things to do, and I can practice technical writing in English. No, maintaining the docs is not just about fixing typos. In fact, it even have the right to its own documentation website!

Want to join?

Astro project architecture

Astro has several repositories, here are the main ones:

• withastro/astro which contains the project’s core;
• withastro/compiler which is used behind the scenes to transform templates;
• withastro/language-tools which focuses on the tools editors need to understand Astro syntax;
• withastro/starlight which contains the sources for the tool dedicated to creating documentation sites;
• withastro/docs which contains Astro’s documentation (and its translations);
• roadmap which allows you to propose ideas (and to discuss these ideas) in order to develop Astro features.

All kinds of skills can be useful

Multiple repositories also mean diverse skills. For example, if you are more of a Go developer, you might be interested in the Astro compiler, while for the core of the project, you will need to know Typescript. If you are more of a wordsmith, don’t hesitate to join the Docs team!

You can also contribute without having a lot of time to dedicate. For example, you can help triage tickets, check the code, or proofread the documentation. If you are on Discord, you can also help resolve help requests. Even occasionally, this type of contribution is always welcome!

Don’t see yourself in any description? My list is not exhaustive, feel free to check if there is a place where you can contribute! And remember, you don’t need to commit full time, even occasional contributions are always welcome.

Before starting

If you are still hesitant, I invite you to read the Contribute to Astro page in the documentation. Next, be aware that each of these repositories contains a CONTRIBUTING.md file. I recommend you read it before you start.

Whether it’s for issues, RFCs or PRs, each repository has templates to fill out. These are not there to annoy you but to save time for people who will try to help you (whether to solve your problem, to reread your contribution, etc.). It’s therefore a win-win system.

Finally, don’t hesitate to join the Astro Discord server. Being there is useful for coordinating if needed, but it can also allow you to find help or ask for advice.