Oskar Dudycz

Pragmatic about programming

How to get started with Open Source?

2021-03-31 oskar dudyczOpen Source

cover

As you may know, I’m an active Open Source contributor. Since December 2020, I’m working full-time on the Open Source project EventStoreDB. I have been the co-maintainer of the quite mature and relatively popular .NET library - Marten for the last two years.

How did it start? I could say it was in the normal way. I went from a user to a contributor to a maintainer. How exactly? You can read the details in my blog post “Revolution Now!’. TLDR - I started as a user, then I found some missing pieces. I told myself: “why not try fixing that?“. Then I became an active community member, contributed more, and here I am. It was a step by step process.

What advice do I have on starting your journey with Open Source?

  1. Start with something small. It’s not the best idea to start with massive PR without discussing it with the maintainers. I began like this. It was not the most prudent move. It’s like kicking in the door of the western saloon. You’re risking a defensive attitude from the maintainers or simply not meeting the repository convention. It is best to report an issue or an idea and ask for tips. You can add that you will be happy to do PR. Start with a simple Pull Request, describe it well, don’t just push the code. Maintainers love small changes, especially to documentation. By starting this way, you can even become a .NET core contributor. The time will come for bigger things. Don’t know what to add? Search the “TODO” in the code: these are good places to start. The maintainers often put the label “Up for grabs” on issues, indicating something that can be a good start.
  2. Join the community. Every popular library has its communication channel, be it Slack, Gitter, Discourse or a mailing list. Join it, check how people communicate with each other and how they help on issues. Verify if this is the place you want to be. From such a channel, you can also assess whether the community is alive. If there are active discussions, there is a greater chance that the library is maintained.
  3. Help others. Open Source, as the name suggests, is about being OPEN. Ask, rejoice, but also help. Even if you do not consider yourself an expert, your advice may be valuable to someone. Don’t be afraid that someone will tell you that you’re wrong. Even if your suggestion is not optimal and someone criticizes it, you will at least learn something new. You will confront your thinking.
  4. Don’t be demanding. You should remember that there is a human on the other side who usually does it out of his passion and at the expense of other stuff. Can you see that something is missing? Contribute.

Do you want to create your Open Source library?

  1. Do something that has value for you. Don’t create the Wunderwaffe. Think about your problem and solve it.

  2. Deliver in small pieces. Do not bury your work on the long-living branch. There is a high risk that you will never finish that. Break it up into smaller pieces and deliver on each piece, one by one. There is nothing more motivating than to finish something

  3. Take care of the documentation. I can assure you that without it, no one will use your library. It’s not that hard: for example, Github gives you the option of automatic documentation generation from MD files with Jekyll. At the very least, make a decent README. Also, check out my other article “How to successfully do documentation without a maintenance burden?”.

  4. Create a CI / CD flow. Many tools allow you to configure a free CI process for Open Source projects expressly: Azure DevOps, AppVeyor, Github Actions, Travis, etc. It can be a basic one. It would be good if it’d check at least if code is building and tests are passing. This is crucial for potential contributors. Nothing is more discouraging than a failing project or needing to make a Build Dance to get started on the code-base. If you’re searching for inspiration, check my article “How to set up a test matrix in XUnit”.

  5. Take care of backward compatibility This is one of the essential elements of creating libraries. The stability and predictability of the API is crucial. If you keep posting Breaking Change now and then, users will either not move to newer versions or quit. Follow the Semantic Versioning rules. Unfortunately, this requires one thing: thinking before coding to not release anything that you will regret later. Read also more in my article “Let’s take care of ourselves! Thoughts on compatibility”.

  6. Less is more. Focus on the little things, deliver fewer features, but better quality. It also applies to technical details: only expose what you want users to use. If you inadvertently make a class public, then if you’re going to throw it out, you may be surprised by how many users are using it and how weirdly and wonderfully they are using it.

  7. Don’t expect to get money out of it. The harsh reality shows that working on OSS is philanthropy. I’m lucky to be working right now on EventStoreDB, which has managed to find a way of maintaining full-time employees (watch our CEO Dave Remy explaining that: https://www.youtube.com/watch?v=HpiPqWmilN4). However, it’s a rare case. From my work on Marten, I managed to get €0. Don’t expect to be paid. The subject of “Open Source Sustainability” is a broad topic, even for a separate email or blog post (if you want me to write about it, let me know!). For now, take a look at the controversy with the Redis license, a discussion about how the creator of one of the main npm packages started asking for support. There are initiatives such as Open Collective, Github Sponsors.

    I’ve set-up also sponsorship accounts there:

    There is already a group of people who appreciated my work enough to become financial supporters. Still, it’s very far from being a good source of funding. So far, it is mainly a form of thanks for my work, and it makes me very happy!

    Therefore, before you start working with Open Source make sure that it suits you. I encourage you to read the excellent post about the fact that Github Stars won’t pay rent: link.

  8. Promote your work. Writing blog posts (like this one you’re reading) helps readers learn from your experience, but it also helps increase awareness of your work. Create your GitHub page, write on Twitter, etc. I assume that you created something because you believe that’s useful. Explain the people and help them solve their problems. Be active in the community. Marketing takes time, it’s far from something that we developers like to do, but it’s unavoidable if you want to spread your works’ usage.

  9. Be prepared for non-pleasant situations. You can find hate in the OSS world, unhealthy and drama situations like the React community event: take a look here. I was lucky enough to be removed from such events. But it can happen to you. If you expose your work publicly, then you should expect criticism. Still, cheer up! There are cases like this: link that can put you on cloud 9.

If you want to get started with OSS, you can check one of my repositories, e.g.:

How can you help?

  • add an issue with what you do not understand,
  • addition or corrections to documentation,
  • new samples,
  • new features,
  • bugfix.

Of course, the best thing to do before a significant change is to contact me. If you have no idea but want to do something, also speak up.

Cheers!

Oskar

p.s. If you’re also considering blogging, have a look at my “10 notes on the 10th blogging anniversary”. I’d like to know them before I start!

👋 If you found this article helpful and want to get notification about the next one, subscribe to Architecture Weekly.

✉️ Join over 11500 subscribers, get the best resources to boost your skills, and stay updated with Software Architecture trends!

Loading...
Event-Driven by Oskar Dudycz

cover

Through my window, I see the result of good plans but poor execution. Opposite my flat, there is a partially completed construction place. Buildings were supposed to be eye-catching Mediterranean style apartments. Delivery date? Two years ago. Actual? More and more unknown.

Some time ago, I heard that using Event Sourcing makes creating Event-Driven Architecture easier. The arguments were correct, that if we’re already publishing events to trigger business workflows, then at some point, we may want to also store events to not lose information. Agreed. However, I also heard that keeping the state as events will simplify things. We’ll have a source of truth with a record of the system behaviour. This will allow, e.g. to confront the results of the operations with the recorded state. I’d agree with that, with one distinction. It’s easier as long as you already know Event Sourcing.

Many people in the DDD community claim that the essential is to properly break down the system into autonomous parts called bounded contexts. Once we have it, the rest is secondary and will sort itself out. For sure.

Many seasoned programmers speak similarly about new technologies. They claim that they can translate past experience into new technologies. That’s true that by analogy, they can catch the big picture quicker. But isn’t it a bold assumption to say that Win.Forms specialist will learn Angular quickly?

The end result may differ a lot from the initial ideas. I saw the plan of those buildings next to me. Now I can see the effects of the execution. Or actually, the lack.

I believe that we should carefully acknowledge not only the point of view of our authorities but also their seating point. If we want to find out how to form a wall, do we ask an architect or a foreman? An architect may know the theory, but the practice is what we’re looking for. On the other hand, if you want to know where to put the wall, you prefer the architect to do measurements. At least if you don’t want to have the roof falling to your head.

After I had torn a ligament in my knee, I went to two qualified orthopedists. One said I should have surgery and do a reconstruction. The second stated that there is no need for that; rehabilitation should be enough. Guess which one had a specialization in surgery and which in rehabilitation?

People usually give us advice from the point where they’re currently standing. They are entitled to a biased view. An architect who rarely does programming will tend to downplay the value of implementation and tactical patterns. Midlevel developers will focus on technicalities instead of the global system impact. The team manager or consultant will emphasize the importance of soft skills (or esoteric techniques known only to them).

The truth is that we need all of them. The excellent plan will fall on the bad execution. The best execution for the wrong case will be just a waste of time. We should carefully evaluate the advice considering what we need and what an expert can give us.

Therefore, when we’re reading an article, watching a talk, let’s also pay attention to the place where the person is standing. The perspective from there may be much different from where we are right now. That can be good, as it may push us in the right direction. But it may also be misleading, as we accidentally take biases of this person without understanding the tradeoffs. Personally, I prefer to follow not only people from pedestal but also those that are closer to my position. A bit further in the journey, but not too far. That helps me to calibrate my view as those people are more relative to my daily struggles.

Polish historical leader Józef Piłsudzki reportedly used to say: “Right is like an ass, everyone has its own”.

Cheers!

Oskar

How to create projections of events for nested object structures?

How to successfully do documentation without a maintenance burden?