Last week I launch my own project at GitHub called Pasolo, a simple single user authentication server using passkeys. I built all the parts, from backend, frontend, as well as releases. It was really eye opening experience for me, I learn a lot of building whole full stack application

Proper release flow

Many times in my professional life, I handle CI/CD pipeline, which mainly handling build, release, and deploy. I could even say, thats one of my expertise in Software Engineering. And yet, building my own project, that I wish can be easily used by other, is not that simple.

First, I am not used to releasing a project using semantic versioning. I do start using semantic commit message, with feat, or chore etc, because it makes my commit readable. But I never done it for release purposes. When I start pushing my code, and want to start share those to the world, now I am facing this problem: how can I build and release it so that people can use it easily

As my project written in Go, I remember tool called goreleaser. A simple tool to help releasing go binary and publishing it to various systems, like GitHub. I set my project with goreleaser, with all the CI config as GitHub workflow, and push it to the upstream.

Then I realised, goreleaser use git tag to determine the version, so I need to tag it to trigger the build. Then my question is: Who do the tag? Is it manually from local then push it? Should this process happens as GitHub workflow too? How about having Release Candidate version from latest main branch? So many questions!

Things that I usually take it for granted from my work, suddenly become an implementation detail that I don’t know the answer. This alone takes quite some time for me to figure it out, at least something that I know now: Pull Request and Push to main only test build. I will tag locally then push it to upstream when I want to release new version. I am want to have release candidate version from upstream, but it’s a question for another day.

Documentation is as hard as writing code

Really! I can’t emphasis enough that, in my opinion, if I want my project to succeed, I must write good documentation about it. This is a huge topic on its own, because good documentation has structure, where people with different background (or in my case, different technical skill) can follow through, hopefully even use the project properly for their use cases.

I start writing all the important part of my project, from why I built that project, my use cases, how to use, how to setup, all available configuration, including examples. Oh boy, writing examples is also takes time, because it has to be tested. From my personal experience, and I do believe that this is common, when reading documentation, following the example and it’s not working, you lose like 40% of your audience trust. It is not rare that I immediately looking for something else when the example is broken.

Conclusion

Developing project is hard, really. Now I respect even more to all the indie hackers out there, open source maintainers that keep their professionalism on what they do. It’s not easy, and sure it’s even not that simple because developing project alone is not enough. Writing documentation, make sure the example works, and market the tools out, in my opinion is as important as the product itself.

Keep developing, folks!