Maintaining a Library and a Community

I'm Marc Erikson and I will be your host for today's talk. Thank you for joining us. I'm excited to be here today and I hope to be able to share a few things with you. Before I get started, I would like to give you a little bit of background on what I do at React. I'm a developer and I'm a web developer. I'm an engineer and I've been working on the React team for over 10 years, and I am a developer and a community.

A couple quick things about myself, half of which Daphne already stole from me. My day job is a front-end engineer at Replay, where we're building a time traveling debugger for JavaScript. I am an answer of questions, I will answer questions pretty much anywhere there is a text box on the internet. I collect all kinds of interesting links to tools and articles and resources. I have a family of blog posts about React and Redux, and I am a Redux maintainer. I've written a lot of our documentation, created Redux Toolkit, worked a lot on React Redux. But yes, most people do know me as that guy with the Simpsons avatar.

So, today's talk is a little bit different for me. Most of my talks tend to be very technical, and today's is really more about people. I was trying to think through, like, what am I actually even trying to accomplish with this talk? And I'd say that the goals for today are, if you're an app developer, I kind of want to give you an idea of what it's like to be an open-source library maintainer. If you're maybe thinking about working on a library, or figuring out how to get started, I want to give you some examples of what it's like, and maybe offer some suggestions or lessons learned from years of actually doing this in real life. And, as always, I'm going to be very brief, and I'll give you a little bit of background. I'll give you a little bit of background, and I'll give you a little bit of background. Let's get into some practice.

So, when we think about programmers, you know, the stereotype is, you know, a programmer is a machine that turns coffee into code, you're hunched over your keyboard late at night, furiously pounding away and trying to build something. And in the same way, I think that when people think about maintainers, it's kind of like a vending machine. And, you know, in the same way that programmers do a lot more than just write code. We're having discussions in Slack channels and GitHub issues. We're planning out architecture, or figuring out how to write loops and YAML or something like that.

And so, in the same way, maintainers do a lot more than just write features and fix bugs. And it turns out that a lot of what we do actually has to do with people. Now, with open-source, there's really this big dichotomy that exists. On the one hand, there's the open-source license. And license is basically boiled down to here's some code, you get to use it for free, and if it breaks, it's not my fault. That's on you. But on the other hand, when you publish a package or a library, there's sort of this community expectation that's very implicit, and it's this idea that if I've made this project, I have to maintain it. And that people expect me to respond to issues and fix bugs and keep it maintained. And that's not in the license, but that is very much in the culture that we've built around open-source.

So, what is actually a maintainer? There was a very good quote from Artem Zakharchenko, who's the creator of MSW. So, maintainer is a person who maintains a library, and maintains a library. And maintainer is a person who is a designer, dev advocate, tech support, salesperson, community manager, tech creator, and a human being all at the same time. That is a lot of different hats to wear. And for a lot of libraries, there might only be one person maintaining it, which is why we have the classic XKCD illustrating the Jenga tower, that is modern technology, and that is what we want.

Now, at one point, I was out looking for some possible job situations a while back. And someone sent me a job opportunity for a developer relations position. And I looked at it, and I was very confused. I'm an engineer. I want to spend my time writing code. Why would anyone think that I'm looking for a dev rel position? And someone pointed out that I've basically been a dev rel for three years. And I was like, well, that's kind of where I got started. It's kind of like, oh, okay. And if you think about, like, I looked up some definitions of what a dev rel does, and it's things like technical content creation, public speaking, community engagement. That actually does sound a lot like what a lot of open source maintainers do. So, for a bit of context, here are some recent download numbers for some of the major libraries in the React ecosystem, which are React, Redux core, Redux toolkit, React router, React query.

And the main thing I want you to take away here is that Redux is still one of the most widely used libraries in the React ecosystem. And so, for me as a maintainer, anything that I publish, anything that I do, is going to have an impact on a lot of people. You know, there are hundreds of thousands of developers using code that I publish, if not millions of them. Basically, everyone in the world uses applications that have my code in it. And that puts a lot of responsibility on me to make sure that I get things right.

There was one time I accidentally published a console log in a hot path in React Redux, and that got reported, like, five minutes after I put it out there. It's like, the things that I do matter a lot, and so I have to be very careful when I publish things.

So, what are some things that maintainers actually do when we interact with our community? And one of the most obvious and biggest ones is, indeed, providing support for our users. Now, in the case of Redux, we handle this in a few different ways. The most obvious one is GitHub issues, as well as GitHub discussions. We try to keep a bit of a separation between issues are for actual bug reports or feature requests, and the discussion section is for non-bug report related things. We have a Discord channel in the React Flux Discord, but also, like, I see questions pop up on Reddit or Hacker News or elsewhere, and I try to answer those, as well.

Now, everyone's going to end up handling this differently. For me, I spend a lot of time naturally reading things anyway. I spend a lot of time on Reddit and Hacker News. I'm not a big fan of Redux, but I do tend to pop up in any thread that mentions Redux, and it's basically just because I keep refreshing things a lot. So, I also spend a lot of time on the GitHub notifications tab. I tend to refresh that a few times a day, and so, any time someone does file an issue or leave a comment, I tend to see it pretty quickly. For myself, I try to leave an initial comment right away, probably just because I've got it open, but also because I feel it's pretty important to try to let people know that someone is actually listening to their question.

But on the flip side, you are not required, like, people cannot demand all of your time. You have to be able to draw the boundaries, not always get sucked in, and be able to have that balance between actually wanting to help and knowing when to step away. Another huge thing that we do is working on documentation. I gave a recorded talk at React Advanced last month that covers this in more detail. But a lot of times, documentation is more important than code. I mean, if you've got a feature published but it's not documented, does it even actually exist? There's a concept called the four categories model of designing documentation that I think is really, really good, and I went over this in more detail in that other talk.

You have to be able to draw the boundaries, not always get sucked in, and be able to have that balance between actually wanting to help and knowing when to step away. Another huge thing that we do is working on documentation. I gave a recorded talk at React Advanced last month that covers this in more detail. But a lot of times, documentation is more important than code. I mean, if you've got a feature published but it's not documented, does it even actually exist? There's a concept called the four categories model of designing documentation that I think is really, really good, and I went over this in more detail in that other talk.

It is very important to keep in mind what kind of people do you expect to be reading your documentation. In the case of Redux, I expect that a lot of our readers are people fresh out of boot camps, and so I have to kind of keep that in mind as I'm trying to organize things. And I would say there's probably no such thing as too much documentation. Some people have legitimately complained that we have too many docs pages, but I would much rather err on the side of having more information and then working to try to organize it than having not enough information online.

So when it actually does come time to design a new feature or an API, ultimately we're trying to offer a tool to our users that actually solves some problem or use case that they have. And so as we're trying to design it, we have this use case in mind, and we're trying to come up with something that will actually allow users to accomplish this goal. But just we have certain assumptions about how people are going to use this API, and then it turns out that people go off and do other things that you really had no idea they were ever going to try to do, or they start doing something and the options aren't quite configurable enough. There's a saying or phrase called Hiram's law, which is that every actual behavior of a piece of code will get depended on by somebody even if you never considered it part of the public API. There's a certain bit of timing or inner behavior and people write code that relies on that, and then you change it because it's just part of the implementation details, and then of course somebody complains that you broke their system.

Some guidelines you might want to think of as you're trying to design APIs. Like what is the actual goal that the user is trying to accomplish? Is this something that can be done just by the user writing some code already rather than having to build something into the library? How many people actually need this? Like yes, maybe one very loud person is asking, but are enough people going to benefit from this to justify building it? Ultimately not all feature requests have to be added. Every bit of code that you add to the library is more code that you have to maintain yourself. Dominic Dorfmeister, aka TKdodo, the maintainer of React Query, just did a great talk at React Advanced last month where he talked about some lessons learned designing APIs for React Query. It is a wonderful thing when some of our users actually file PRs for contributions. And I'm not joking, like even if it's just literally fixing a one character typo in the docs, I appreciate it when people have filed PRs. But there's the whole range from the one character bug fix all the way up to here's a brand new feature that I've written from scratch with tests which is like the rarest thing ever but has happened. It's wonderful when that happens, but it does take time and effort from me as a maintainer to actually review it and understand it and decide that it's ready to merge. If you can add like a contributing guide page to the library, that can help provide some guidance to the users who want to actually contribute, ultimately the more that a user can do to make it easy for me, the maintainer, to understand and review, the more likely it is that I can actually trust that it's ready and merge it. Sometimes people file things and it's like I think this could be useful, but like I don't have time to give you guidance to make the tweaks. Maybe it's easier for me to just take it over and do it myself, or maybe it's even a valuable thing, but I don't have the time to think about it and so it's just going to end up sitting or not getting merged. Like there is a time cost for the maintainer involved in this. Package versioning. Package versions act as both a code contract and a tool for managing user expectations. If I put out a patch release, then people are going to expect that they can safely update and it's just going to work just a little better.

If I put out a patch release, then people are going to expect that they can safely update and it's just going to work just a little better. If I put out a major version, then the expectation is that they're going to have to spend a lot of time reviewing migration guides. Because of this, it's very important as a library maintainer to put together release notes and change logs to actually tell people here's what's changed, here's what you can expect, here's the kind of things you need to be keeping an eye on in your code. But there's a lot of considerations that go beyond that.

As you're developing a feature, how are you managing the pre-release versions? One thing I've learned is that it doesn't matter how many pre- release versions and alphas and betas and RCs I put out, eventually you're just going to have to publish it and then people will finally try it out live and tell you all the things that are actually broken, and I would love to get more pre- release feedback, and in practice it really just doesn't happen. At some point I have to trust that I've done enough work and then publish it and then get the bug reports. What happens if you fix a bug and technically the bug fix changes the behavior? Is that a patch release or is it a major release? A lot of that is really up to us to decide. For me it's basically been what did we intend it to be and if the behavior is something that we consider broken, then it's a patch release, it's a bug fix, even if the behavior change could be argued that it's breaking in a major. What happens when you change internal behavior? What happens when you change TypeScript types? How often should you put out new major versions? These are all things that we have to consider as we're managing the library.

So, breaking changes are sometimes necessary, but they are going to cost time and effort for all of our users. Like I said, we have a lot of people that use Redux, so if I make a breaking change, I'm inflicting some amount of pain and effort on hundreds of thousands of developers, and so that has to actually be worth it in the end. Package managers are always installing the latest major version, and so I have to think about if I put out a new major, what is going to be the impact of people automatically installing the newest version in their systems? For me, my goal is that even in a major version where there are breaking changes, I am still trying to minimize the amount of actual pain and effort and breakage that goes into the user's systems. One way you can do this is with code mods, little scripts that can automatically look for patterns in the code and rewrite them so that you can maybe change, like, an old broken option into a newer version of the code.

We've been publishing packages on NPM for, what, 15-plus years now, and in a lot of ways, still nobody knows what we're doing. Everybody's borrowing from everybody else. ESM versus common JS is still pretty much a nightmare. I spent almost all of last year trying to modernize 3DUX packages, and while I sort of eventually came up with something that works, it was a very long and frustrating process. I wrote a long blog post about that one. And this still kind of comes down to maintainer preferences. Some maintainers have chosen to just publish ESM only because it makes it a lot easier for them, but that means that if you're trying to use it in a mixed environment, it might be harder. I have tended to be more of a compatibility maximalist, where I just want my package to work out of the box for as many users as possible, and I'm more willing to take on the pain and suffering to make that happen.

A couple minutes left. A couple real world examples. I have a long version of this rant, but I'll keep it relatively short. A lot of boot camps and courses are still teaching outdated Redux patterns. The old hand written Redux style instead of the modern Redux tool kit. And we want everyone to use RTK, but beginners aren't going to read our docs. They're just going to follow whatever course or instructions they're getting. So a couple years ago I made the decision that I'm going to modify the documentation comment for the create store method to mark it as deprecated, so that it gets the little strike through when you import it.

So a couple years ago I made the decision that I'm going to modify the documentation comment for the create store method to mark it as deprecated, so that it gets the little strike through when you import it. Now, no, this is not a run time error. It doesn't even break anything. It's literally just there's a strike through. And the idea was that beginners would import it, hover over it, and see a documentation comment that says, this is outdated. You should use Redux tool kit and follow the link to our docs page. So I shipped this in Redux version 4.2, and the release notes very clearly explained why I was trying to do this. So, you know, the release notes saying, you know, we are not actually removing create store, and here's an example of what this will look like. And that's it. And if people didn't like it, they can either, you know, modernize to Redux tool kit, they can leave it alone because nothing breaks, or they can switch to the new aliased legacy underscore create store method. And a lot of people did not like this. We had people yelling at us because they somehow didn't want to use Redux tool kit. The one that really got me was people telling me, you just want people to use your library instead of Dan Abramov's. It's like, wait a minute. Dan created Redux, but he only worked on it for one year. At the time I had been working on it for seven years. It's like, and I published both Redux tool kit and the Redux core. Do I not have the right to say how my library is supposed to be used? I'm doing this with the best interest of my users in mind. Now, even in Redux version 5, which came out last year, I could have removed create store. It's a major version. I'm allowed to make breaking changes, right? But I didn't want to actually break user code. I'm trying to give them a nudge. I'm not trying to, like, destroy the ecosystem.

One other example, I spent all of last year working on Redux tool kit 2.0. Most of this was about modernizing the packages for better ESM compatibility, dropping IE11 support, that sort of thing. This was a hard effort and ultimately this was about trying to make it work better for our users out of the box. But to do that, I had to look at the 150 plus open issues related to the RTK query data fetching feature and just say, we're not going to touch any of that. So basically putting my project manager hat on and cutting scope in order to ship and meet a deadline. We did end up putting out a very large migration guide with a lot of details about all the things that actually changed and what users would actually need to do.

So, takeaways. There is no actual manual for being a maintainer. It's something we basically all learn on the job as we go. And it is basically another full time job or can be a full time job and we really have to enforce a lot of boundaries ourselves to maintain that work life balance. Anthony Foo has a great post about mental health and dealing with open source and I basically, I endorse everything he said in that post. Ultimately, maintaining is really about dealing with people and expectations far more than it is actually writing the code. And it can be very draining and stressful, but it's also very rewarding to know that the work that I've done is having such an impact on the ecosystem and affecting so many people's careers. So, those are some thoughts and experiences from my time maintaining Redux. Hopefully that is useful or insightful or maybe even encourages you to work on a library of some kind. Thank you.

Okay. So, we have a few questions rolling in. People are wondering, okay, this one is from, oh, they're all anonymous. Okay. What's your take on if or how maintainers should be compensated by users? Specifically, any thoughts on the core JS drama?

A couple different questions. So, this goes back to that kind of legal versus social contract thing. Like, when I publish open source code, I am explicitly saying that legally anyone is allowed to use this code, whether it's importing the package or copy pasting, modifying it, whatever, and I'm not responsible for if it breaks, but also you're not obligated to give anything back to me. On the flip side, we've got widely used packages that are being used by massive corporations making billions of dollars, and so conceptually it feels like, especially big companies should be giving back to the ecosystem and at the same time legally they're not required to. And there is no good answer for this.

I'm fortunate to have a day job where I'm not trying to rely on my open source work to pay my bills. There's a lot of people who have put in time and effort who want to be compensated for that, and I think that's a very understandable position as well. The concept of paying open source maintainers is something that's been debated endlessly online. There is no good final answer for that right now.

Next one upvoted from Nicholas. Any recommendations for creating code moths to ship along major versions? Let's see. There's a number of tools for code moths out there. I think one of the older ones is called JS code shift. There's a company that has created a bit of a SDK for creating code moths that is literally just code mod, I think. I believe they just took over ownership of the various react-related code moths. I don't have more of a link off the top of my head, but that's probably a good starting point to look. Okay. So code moth. Awesome. Thanks for that.

How do you keep your maintainer GitHub separate from your day job GitHub? I don't, which means that when I wake up in the morning and I mash the F5 button on the notifications page for the first time, I have a mixture of stuff related to the work repositories, the various redux-related repositories, the comment thread that I commented in five years ago that just got necro posted in. I would love a more advanced version of the GitHub notifications tab. In my case, it all gets mixed together.

How do you keep your maintainer GitHub separate from your day job GitHub? I don't, which means that when I wake up in the morning and I mash the F5 button on the notifications page for the first time, I have a mixture of stuff related to the work repositories, the various redux-related repositories, the comment thread that I commented in five years ago that just got necro posted in. I would love a more advanced version of the GitHub notifications tab. In my case, it all gets mixed together.

Okay. So they all jumble up. Okay. All right. So how do you handle the analysis paralysis when designing an interface knowing that it's impossible to change in the future? It's not impossible to change, but you're definitely kind of locked in until the next major version, which might be a while. I mean, here's the current example. So like I said, we've got something like, we had something like 150 open issues related to RTK query requests for features, bug fixes, whatever. The single most requested feature right now is infinite query or pagination support, which is something that React query and SWR have that we don't have in RTK query. And it's been on my mind for a while, but I've been too busy with life and other responsibilities to take a look at. I finally had time to try to do some research and get up to speed on that domain about a month and a half ago. Someone else had filed a draft PR earlier this year that basically tried to mimic React queries API on top of RTK queries internals. And I kind of looked at it like, okay, great, the PR exists. I don't have time to understand this. Hi. And I finally had time last month to sit down and go through the PR, try it out, understand what it's doing so far, figure out like, understand for myself where is this broken, what starts to need to change, what are the next steps, had actually had a discussion with Dominic, the React query maintainer about why they made certain decisions in designing their API. Yeah. Like I said, like, there is no stopping point. Ultimately you're looking at the code, and it's just like anything else. Like we think this is good enough, ship it, and then you're stuck with whatever you shipped. Yeah. For sure. Okay. We have time for one last question. How much do you lean on automated tests to prevent regressions when someone contributes? That was a good question. A lot. So it's funny because I'm not that great at rating tests at the day job, but when it comes to a library, like I'm all about those automated tests. Like both to define the behavior and like if you fix a bug, making sure that you've got a test that captures that bug fix is really important.

And so this goes back to the external contributions thing. If someone files a PR to fix a bug or add behavior, I really want them to include some tests, both so I can see that, the CI is still green, as well as it gives me more confidence in looking at their code and to feel good about what I'm now taking on the burden of maintaining going forward.

Yeah. So I guess this is a PSA. If you contribute, please write tests. If you file PRs to libraries, please take the time to include tests. It makes the maintainer's job a lot easier. If you want to make Mark happy, that's how you do it.

Nice. All right. If you have more questions, we didn't get through everything. Please find Mark in the Q&A room or just around the conference. Really, thank you for your time, and go support the open source developers and library maintainers. Thanks for what you do.