Contributing to Elixir and the ecosystem - ElixirConf US 2020 (with transcriptions)

Have you ever wanted to contribute to the Elixir ecosystem but was not sure what to do or was afraid that your contribution would not be good enough? In this talk, you'll learn practical tips and tricks to give the first steps.

More info at https://2020.elixirconf.com/speakers/130/talk

Full slides without transcriptions available at https://speakerdeck.com/leandrocp/contributing-to-elixir-and-the-ecosystem-elixirconf-us-2020

Transcript

1. Contributing to Elixir and the ecosystem @leandrocesquini @leandrocp leandrocp.com.br Hey everyone. My name is Leandro, those are my handles to find me on Twitter and GitHub, and also my blog where I post articles once a year or so I'm super excited to be part of a conference that has been my source of learning and fun for the last few years, and I would start this presentation by asking people to raise their hands if they never contributed to open source before so I would get to know my audience but I guess that's not gonna happen today. At the same time I must confess that I always had this fear of public speaking with people starring at me but I kind of miss seeing some faces, so I hope it doesn't sound too awkward. So, why this talk? I have been working with Elixir full time for the past 4 years or so and I made a few contributions with code, podcasts, meetups, articles, and some other stuff, and I have learned a thing or two in this process that I'd like to share, and besides that some friends ask me "hey what should I do to contribute back to the community?", or "can you give me a few tips?". This talk is my answer for those questions and my goal here is to inspire who wants to contribute back to the community
2. The most important fact I can say about myself is that I'm just like you, I'm a software engineer who writes code every day, discuss code reviews with teammates, avoid deployments on fridays, and stuff like that, and sometimes contribute back to the community, but I don't consider myself an open source guru or something. I hope it's comforting to know that, because I feel the impostor syndrome is real and you may believe that contributing to the Elixir ecosystem is an impossible task or at least require some kind of Jedi level, but If I do my job well with this presentation you'll realize that there's a pragmatic path you can follow.
3. We are helping PreK-12 schools, families, and communi=es implement a new approach to promote student success. I work at Intellispark, where we are building a platform to connect students, families, and professionals to help kids to have success on their education. And that platform is built entirely in Phoenix and LiveView and an interesting fact is that we have been using LiveView since v0.1.1, I guess we like to live on the edge but actually it has been working very well, so reach out if you want to know more about our product or how we leverage LiveView in our benefit.
4. My last name is Pereira, which is a confusing word to pronounce in English, and often people ask me how is to live in Portugal but actually, I'm from Brazil, you know, that part of the world where Elixir was born and also the place where there are no seasons except of course summer, it's always summer there, and usually the temperature goes from hot to burning. And now I'm living in...
5. Canada. Now I can feel all the seasons, especially the winter.
6. Like I said before, I'm a software engineer and some time ago I was reading this Erlang documentation, which by the way I recommend.
7. And I found this: the word "to" was duplicated. At the time I thought it was a good idea to fix it, I mean, that was not right so why not fix it? All I had to do was to find the file and send a pull request...
8. What could go wrong, right?
9. Well, not reading the contribution guide and messing up with git dit not work very well. It happens.
10. Making mistakes is part of the process Before we dive into the topics, it's very important to keep in mind that making mistakes is part of the process. Don't let them stop you, don't feel that someone is judging you, I believe it's quite the opposite, you're trying to do something good, you are adding value to our community, or at least trying to, so you should be good. Try to learn with them and move on. That's an important lesson, keep that in mind.
11. h@ps://twi@er.com/alexcasdev/status/1284893939519152131 People may have many different reasons to contribute to the Elixir ecosystem You may want to learn more, promote yourself, give back to the community, fix something that's on your way, making new friends, endless reasons. That's the "why" and it's very personal so I won't talk about it This talk is about the "how". How can I start? How can I give the first step? How to get help? What can I do? Those are popular common struggles and also It's pretty common to believe that you need to create something new to be doing open source but that's not really true With that in mind, let me present some practical steps to overcome those struggles and a different approach to get you started
12. Hello World Ok, so how can I give the first step? When you are learning or playing with a new language, we have this concept of "Hello World" to give it a try in 5 minutes, it is a quick and easy way to get something done. But what about open source?
13. Contributing to documentation is the hello world for open source Turns out we can consider improving documentation as a first step, a great one actually. Contributing to documentation is like the "Hello World" for open source, but with even greater benefits
14. Good documentation in the Elixir ecosystem is considered as important as the code itself. You may have felt how much effort and love was put on documentation when working and reading docs everyday, and how that's important. Those docs have clear instructions, examples, guides, and so on. But they are not perfect. Actually, it's pretty hard and time consuming to keep them updated, well written, and improve them over time. That's a community job. When I say documentation, I'm not talking about functions only, but any place where we developers seek help, like for example guides.
15. Which are very useful for our daily job
16. Be it a guide to installation or a guide with instructions for programming
17. Or also notes that will save the trouble for another developer
18. Or maybe fixing an example that would cause a bug, again, saving someone from getting into issues
19. Or document missing options that a function accepts
20. Or clarify the behavior of an existing option
21. And of course documentation also includes metadata and specs
22. Well, I could spend the whole day showing how documentation is valuable, but I promise that's the last one. In order to improve documentation, you don't need to write a book, a single word fix would be enough. The goal here is to improve the developer experience, any letter you change towards that goal is valuable
23. Another benefit is that you don't need to spend days to contribute. Just find the file, edit the file, and send a pull request. That's it. Now you may be wondering if helping with documentation is so useful as helping with code, but think about that time when you could not find what was wrong with your code and you lost hours trying to fix it, now multiply it for many other developers that could get into the same situation. Also think about the experience of working with a library that has no documentation and another one that has good documentation Contributing to documentation has a huge impact to our ecosystem. Finally, remember that our community has published more than eleven thousand packages at this time, which means you don't need to be limited to Elixir only, look around and try to help that library you like or use every day because there's a lot of room for contributions.
24. Tests Now you may be asking "ok, so what's the hello world for contributing with code?", and turns out the answer is tests. Reading tests is probably the best way to discover how a project or library works internally, but I want to show you something more practical, something that may give you an opportunity to contribute more easily. Elixir and libraries, be it official or from the community, they usually have a good suite of tests, but sometimes important blocks or lines of code may lack test coverage, it may be a new feature that doesn't have test for all edge cases or something that has changed and also doesn't have coverage. And that is where you can help: improving the quality of tests. Let me show you a couple of examples
25. For those who never saw a screen like that, it's the output of running all tests and the lines in red indicate those source code lines which are not tested. This one was from the Plug library. The test coverage was showing that basically passing a map to a plug was missing a test. Of course, it was working because that's pretty common to do, but adding a test will guard against unintentional future breaks or can help other people when reading the tests.
26. Another example from Plug and basically the same scenario. Look how the get macro has coverage and others don't have. Again, of course, that was working, so it's not about fixing it, it's about improving the test suite. Look for important lines that have no test, those are potential opportunities to send a pull request The same advice for documentation fits well for this approach, don't be limited to the Elixir repository, look around
27. h@ps://github.com/parroty/excoveralls Let's see how to do that in some steps: firstly of course choose a project you want to contribute to, install the excoveralls package and configure the coverage options, then just run it and open the coverage report. That's all you need to get the test coverage for that project. You'll find libraries with almost 100% coverage or much less depending on the library, so focus to find important lines that are missing tests. For eg, a library that exposes some public functions and is lacking a test for any of them, completely or just a specific part of that function, and another eg is when a function has conditionals and not all of them have test coverage, or branches on the code for dealing with edge cases. Those are some examples of good candidates to send a contribution, but that really depends on the library and you'll need to navigate through the code and the coverage report to find out. Keep in mind the goal here isn't about increasing test coverage to 100%, instead, it's to find blocks of code where adding a test will improve the project and the quality of the tests I will not show in details how to fork a project and send a pull request because there are a lot of good and free materials showing how to do that, so let's use our time to talk about more stuff
28. Asking You may get to the point where you're not sure if you should send a pull request or not, or maybe you're not sure how to write that documentation or code. Don't worry, that's fine, you don't know all the internal details, you're still learning, right? And your first contribution may not be so straightforward or easy, but you have two valuable resources that you can use. First is reading similar tests or code that can be used as a base to write new code or change existing lines. And the second one is asking for help. The best you can do is to ask for clarification on an issue, like asking which files you should focus, ask for guidance to fix that issue, or ask anything you need really. If you already have some experience with that code base, you can just send a draft pull request to ask for feedback
29. I could show you dozens of examples but I don't need to. The core team and the library authors usually puts a lot of effort in pair programming and code review to help you with your contribution, so it's totally fine to send incomplete draft pull requests or even code that may not be so correct
30. The lesson is: if you don't know, just ask.
31. h@ps://groups.google.com/g/phoenix-core h@ps://groups.google.com/g/elixir-lang-core Last but not least, both Elixir and Phoenix have a mailing list to discuss the development of features or changes that could cause a larger impact on the codebase, so that's the place if you want to propose something or if you want to help with some proposal. Libraries usually don't have a mailing list, then opening an issue on GitHub would be the best approach
32. What's next? Those are really the first steps, but keep doing them until you feel more comfortable with the project to discover more about its details and how it works internally. You can also leverage tools like debuggers to learn more about the code, but that's another subject which is out of the scope of this presentation Ok, but which repositories could I contribute to? Try taking a look on the libraries you already use first because it's easier to spot bugs or documentation that you can improve when you use that library every day. On the repository you may find issues labeled as "good for first contribution" or "level: beginner", which as the name suggests are the ones you can take to begin contributing to that project, but If you are still lost when you try to fix those issues, don't get frustrated because there's no magic pill, it's part of the process. Just keep practicing until you get to the next level. Another great way to help is to reproduce the issues, you can create a project just to reproduce the problem and comment on the issue to help the maintainers. Doing that will improve your skills and knowledge. Another tip is to enable GitHub notifications for some other projects to keep track of new issues or pull requests and take some time to study them because they are essentially a free source of knowledge, you can learn a lot by reading what other people are doing and discussing. If you get stuck, you can always ask around on forums, twitter or slack. And remember to always read the contribution guide and other guidelines that may be present on the repository to avoid problems or having your pull request closed.
33. In case it's not clear, let's see a real world example. This issue didn't look too complex to fix, maybe just check the app name and raise or display a warning. So I decided to take a look on this issue
34. To be honest I had no clue where I should start. I knew it was related to umbrellas apps and it happened after calling a mix command. That was all I had
35. And then I found this file that gave me some light, like I said before reading tests is a great way to find more about the design of the project. The next step was to fork the project, run the tests to make sure everything was green, and play around with those tests, mostly changing them to see what happens, what breaks, and what files they impact. That's probably the hardest part, and like I said before there's no magic pill. But have you noticed how that's not much different from fixing a bug on your own project? The main difference is that usually you have to figure it out yourself, you have to read the code, debug and follow it, change tests to discover what's going on. It's like an experiment, but It's just Elixir code, there's no secret besides understanding the design. I get it's not easy, but investing some time to go through the code will have good outcomes.
36. And then I decided to send a pull request, explaining what I found and what I did
37. And that was Jove Valim's response. You see that my code wasn't great, but he gave me another piece of the puzzle so I could continue working on that PR
38. And after some debugging, some IO.inspects, discussions and code reviews, I finally made it work
39. And it was merged! If you can not find someone that is able to explain the code and the design for you, you really have to dig in until you realize what files you should look, which functions are responsible for each logic, the workflow, and so on. The more you get involved, the more you learn.
40. h@ps://hexdocs.pm/elixir/master/library-guidelines.html Two golden tips I can give to you: the first one is to read the Library Guidelines located at this link on this slide, and the second one is to keep the code simple, there's no need to write fancy code, just the minimum that works well. That's how Elixir and other libraries are built, which means you will have more success if you follow those patterns.
41. Writing Maybe writing documentation or code isn't what you like to do, but fortunately, there are other ways to contribute to the ecosystem. Now let's talk about writing articles. It's not rocket science but let me give you a few tips on how you can write and publish it
42. Intro TLDR; at the beginning or at the end (op5onal) Main content Leverage code snippets and images to explain your ideas and opinions. Objec5ve 5tle First step is to work on the structure of your article, let's go piece by piece
43. Objec5ve 5tle Take some time to come up with a good title that's short and self-explanatory. That alone might be the reason someone decides to read your article or not
44. Objec5ve 5tle Some platforms will present a header image that will help to grab the reader's attention, which is hard to get among so much information on people's feeds nowadays
45. Intro Objec5ve 5tle Ok, the title and the header image are both good, but you still need to convince the reader to actually keep reading. The intro is your chance to do that, which can be also used to promote your article on twitter and other platforms
46. Intro TLDR; at the beginning or at the end (op5onal) Objec5ve 5tle That's optional but it's worth mentioning it. If your article has a conclusion for a hard problem or a technical solution, consider adding a Too Long, Didn't Read section to make it easier for people to find what they are looking for
47. Intro TLDR; at the beginning or at the end (op5onal) Main content Leverage code snippets and images to explain your ideas and opinions. Objec5ve 5tle And finally the main content. It's up to you to write it well and find inspiration to write, but it doesn't need to be about complex subjects. Maybe you had some hard time to accomplish a task on your project and could not find an article about it, maybe you had an idea on how to approach a problem, or want to explain how a library works. There are many possibilities you can explore
48. • Grab a header image at unsplash.com, freepik.com or similar • Publish to popular plaNorms such as dev.to and medium • Post to elixirstatus.com • Email to hugo@elixir-radar.com, subject "Please consider this blog post for Elixir Radar" • Share on twi@er I promise those are the only bullet points in this presentation, and of course let's go through each one of them quickly. Try to find a header that has some meaning to the actual content, as a way to link them About platforms, there are others and you may not like like some of them, but not publishing to a platform means reaching less readers Post your article to aggregators in order to reach more readers and have a chance to get your article featured on newsletters Finally use twitter as a promoting tool, no need to pay for ads, just talk about your article when you publish it And speaking of writing an article, you don't even need to host a personal blog, again you can use existing platforms to jumpstart a new blog for yourself
49. Speaking Don't like to write documentation or code? Also don't like to write articles? Fair enough, but you may like to speak and that's another great way to help the community.
50. h@ps://github.com/elixir-lang/elixir/wiki/Podcasts-and-Screencasts h@ps://github.com/elixir-lang/elixir/wiki/Conferences h@ps://www.meetup.com/topics/elixir/ There are a lot of conferences, podcasts, and meetups where you could share your thoughts, which means there's no space to put all of them in this slide but you can keep track of what's happening in those links. Creating content is not an easy task, and conferences and podcasts are not different. Usually podcasts, just like conferences, accepts suggestions or proposals for talks and episodes so if you have an idea to share, consider reaching out, they will appreciate your help
51. And that's a friendly reminder that sooner or later your contribution will be denied. Yeah, that's not cool but happens. What you believe is right or better may not be aligned with the project maintainer ideas or what the project needs at that moment. But that's not the end of the line either. Your contribution can become a new library or you can write or speak about it.
52. Oh and remember that pull request that I messed up?
53. Well, I sent another one and it was merged! You don't need to be part of the core team, or create a popular library, or do whatever you believe is needed to gain a pass to contribute to the ecosystem. And your first contribution may not be perfect, actually, most things we do at first are not great and here I am giving my first international talk to prove that's true. What matters is to share knowledge and deliver value. You can make the difference even with small contributions and taking small steps, and you can do it now
54. Thanks! @leandrocesquini @leandrocp leandrocp.com.br Thank you very much