Related articles
Create an open-source project on GitHub, incrementally
The idea (beginning of September)
After talking to junior developers looking for their first job, I decided to gather resources for Ruby On Rails developers. I wanted to bring together websites, articles, anything that could help developers find a job, prepare for an interview, find an online community, develop their careers...
First delivery (September 14)
My original plan was to do a ReadMe single page. There are lots of such repositories on GitHub (with thousands of stars) and it seemed like a pretty decent solution. Since it would be public, anyone could make a Pull Request to improve it. I organized the links on the page by categories, there was even a summary with anchors leading to titles on the page. I got my first star and thought I had a good start!
Project Update: init Docusaurus (September 18)
I looked at all the projects like the one I had in mind in my star-studded repositories for inspiration and I found The Tech Interview Handbook. He had a nice website. As I looked through it, I saw references Docusaurus and I decided to add it to my project.
Basically, Docusaurus gives you a template for your open sourced documentation. It's built using React and the pages are in markdown format. The good thing for me is that you can have a link to “Edit this page” on each doc page to directly open a Pull Request if you want to make a change. I could have opted for something else like Just-the-Docs But, hey, I saw Docusaurus first.
Update to Docusaurus v2 and start writing (September 26)
I made the switch to v2 because I thought the model looked nicer and also had a dark/light mode, which everyone seems to like. Before the official launch, I wanted to write a few pages of documentation. I didn't want people to go to the site and find it empty, I wanted to give them a taste of what it could be.
First deployment! (October 4)
What's also great about Docusaurus is that you can deploy it using GitHub pages, And Tada, you are live !
Before deploying the site, I filled out the ReadMe with all the technical details, focused on how to add content (the anatomy of a markdown file in Docusaurus), and didn't put much effort into describing how to contribute to the repository.
October 9: Writing the first issues
At that time, I was reading articles about Hacktoberfest and how to contribute to open source. One of the points raised was that if I thought of something that could be easily coded, I should refrain from doing it myself and should instead write numbers to allow other developers to contribute. So I wrote several issues labeled “good first problem” for other developers to get on with.
The first contributor has arrived! (October 11)
To be transparent, the first contributor is the friend who started the deposit from the start. She spontaneously wrote about one of the problems she was ready to do. In a few days, she proposed an interesting solution and obtained the fusion of her first Pull Request on the project.
Effective implementation of my open-source repo (October 15)
You would think that my project was already open-source at the time since the code was public and someone was contributing to it.
Thanks to the excellent open source documentation by GitHub, I realized that some documentation was missing:
- A license
- a contribution file
- a code of conduct
- An update to ReadMe
I chose my licensing thanks to the site”Choose a license“who made it easy for me by clearly explaining the various existing licenses.
I moved almost everything I first put in the ReadMe to the contribution file. It took me a long time to describe the Pull Request processes or the technical aspects of the project. I thanked myself for that later by writing an issue or replying to a comment with links to the relevant parts of the file.
I chose a code of conduct existing instead of writing my own to save time. I chose the Contributor Covenant Code of Conduct because the Rails community uses it.
I finally had to rewrite the ReadMe. I added the purpose of the project, goals, and links to the documents described above.
I even created models for new issues or new requests for review. Now, every time someone creates one of these requests, they have guidelines to help them complete them.
Finally, I decided to put the pages that remain to be written as projects in the repo. I created a project for each section of the site, such as: “How to find a job”, “How to train”, “How to get inspired”... The projects are organized into three columns: “To do”, “In progress”, “Done”.
Each card represents a page to write, with to-do lists for the topics to be covered on the page:
Kaban page for the resources page on how to find a jobA second contributor! (October 19) 🎉
Add some cool bots and branch protections (October 21)
Because what is the point of being a web developer if you can't do things for fun? I added the mention”all contributors“to highlight the contributions made. You may have already seen some of them at the bottom of the deposits:
ReadMe “Contributors” section
I also added the first contributions to welcome contributors when they make their first pull requests or problems. October 21 is also the day I accidentally deleted the gh-pages branch used to build and deploy the site as a GitHub page... Someone kindly pointed out to me that the site was returning the most dreaded thing: a 404 error. After restoring the branch, I set a rule so it wouldn't happen again as easily (I did the same for the master branch, just in case).
Reflection on what will come next (end of October, beginning of November)
I'm currently thinking about adding a CI/CD to at least automatically deploy the merged branches (if I'm fancy, I'll add a linter) .Can't wait to see the feature launch GitHub repo discussions. For the moment, discussions are being held on issues but they are quickly congested.
My point of view
You Learn A LOTP by setting up an open source project. You need to learn to set up a repository for several contributors. If you take the time to write documenting, you will decide on workflows that you want for your deposit. You will make conscious decisions and define what you want from a problem or a takeover request.
The more you write about your project, the more people there will be who can join you and help you. It's cool to know how to do something, but explain it to a potential reader, it's something else! Thanks to questions from your contributors, you can also improve your project over time.
It feels good to recognize that this simple thing that you are doing is in fact a difficult task that you have mastered. It's also a profound humbling experience that forces me to continually strive to write better tools, documents, and blog posts.
In many articles on creating an open-source project, we tell you that you need be patient to find contributors. I was lucky to already have an active community of Ruby On Rails developers thanks to Meet-up that I currently animate. But I also did not hesitate to ask for help if I thought someone would be perfect to review a specific PR or just to Encourage people to contribute. Exposing issues in the open is also a good way to get people involved.
Finally, having an open source project changes perspective. The aim is not to write code and get as much out of it as possible, but to Empowering others to write code. Your success is not measured by the progress of your project by your will alone, but by the number of people who can join you, feel safe and contribute. You help people help you. It's my kind of jam.