Contributing To Open-Source For The First Time

all right new camera new lighting new haircut and all of this because I wanted to talk about my open source stabio so I recently contributed to open source a real open source project for the first time and I'm pretty excited about it now on the surface a lot of people probably don't care about this but if you're new to open source or trying to get into open source I wanted to share my experience and talk about the things that went well and some of the things that didn't go so well so that you can apply them to your own open source experience and it's just a pretty spicy story in general so let's hop in and talk about it so setting the scene I recently switched to neovim as my primary editor and I've been working a lot more in the web development World recently and specifically I've been using a test Runner called vest instead of something like just so putting these two things together I installed a neovim plugin where I could run vest tests within my neovim instance so the typical scenario where you have your test Runner within your IDE but eventually I ran into a problem where the neoven vest test Runner wasn't working from out outside the root of the project so in order for the test to work I would have had to start my neovim instance from the project route which wasn't always the case specifically in mono repos where I would be like two levels up in the file tree and trying to run tests in a sub project within the monor repo so whenever I tried to run these tests from higher up they would just fail because it wouldn't be able to find the files from where I was in the file system so I started to get a little bit nervous because I work in a lot of monor repos and this plugin was just not cut it for me in a monor repo so in the past I always used to just complain in situations like this when I had problems with software and I would just end up not using the software but I recently realized what the heck I'm a software engineer this is an open- source project I can I can just contribute and fix it which is like the most primitive idea behind open source software but I was just never actually contributing to open source software and fixing issues that I ran into but that mindset that was the old me I don't think like that anymore we're going to fix this and get this working in monor repos so the first thing I had to do was get the plugin running locally so that I could reproduce the issue make changes make the fix and do all of that with a faster feedback loop so starting off was pretty clear I forked the repo and then cloned it locally so that I could work from the fork and then push to it as well now I did notice the project had unit tests so I was hoping that I could reproduce the issue in a unit test and fix it from there rather than having to use the plug-in in my actual neovim fig which I wasn't sure how to do but unfortunately whenever I would run the test script it just wouldn't work and keep in mind this was my first time ever doing anything with neovin plug-in development so maybe the fix was straightforward but I did not know how to get these tests running at first so unfortunately I did have to figure out how to actually run the neovin plugin locally which thankfully was pretty straightforward and it was supported with my existing package manager so now that I had everything running locally it was time to try and reproduce the issue in a simple and environment and conveniently the plugin already had an example directory that had vest set up which was really the perfect place to try and reproduce this issue so I added setup files to the example vtest config pointing to a relative file so I expected that the setup file would get picked up if I was running neovim from the vest project route but if I've ran neovim from another level up in the file tree then the setup file wouldn't be found and the test would fail but before I was able to reproduce that I actually ran into a completely separate issue and that was that this plugin was looking for a config file named vest. config but the current config file was named vconfig and according to the vest docs vest should support both so I was thinking H maybe I should fix that too while I'm here but for now I decided to just rename the file to vest config so that I could reproduce the issue which did indeed work I was able to reproduce so running the ofm from a folder up from where the vtus project lived and attemp to run the test the setup file wasn't found and the test could not be run so next up was the fun part the part where Legends are made legacies are created and that is fixing the issues and even better other than configuring my neovim config I've never really written my own line of Lowa code in my entire life now the first thing I noticed was that the plug-in had an option for overriding the command working directory so what I was thinking is we could override the command working directory with whatever the path is to the vest config file so just to verify this idea I decided to hardcode the command workking directory and see if it would work and that did indeed work so at first I was pretty excited about this so all we had to do was figure out how to set the right command working directory based on where the vest config was located but it just didn't feel like the right solution because what if projects out there using Vest were changing their vest configs with the expectation that they would run them outside of the project r directory so with that idea I was afraid that this change with changing the command workking directory wouldn't really be backwards compatible with existing vest configs out there so even though it might work for me it probably wouldn't work for everyone so with that in mind again I decided to take a step back and instead look at the code for the sibling just plugin to see what they were doing because I have used the just plugin as well and I knew that did work in monor repos And to clarify my suspicion that setting the command working directory was not the right solution I noticed the just plugin was not setting the command workking directory and that's when I noticed that there were two fundamental differences between how just and vest set where tests are run from so neoen plugins aside just run tests from wherever the just config is defined plus whatever the root dir config option is where v test on the other hand runs test from whatever the terminal command working directory is plus whatever the root config option is so overall the neovim v test plugin was working according to how vest is supposed to work so in that case this isn't really something that the plug-in should solve and is just the way things are supposed to work in vest so I felt pretty content with that Discovery and now that I understood how vest was determining the root directory I realized that I could just set the root config option to the special dur name Global to ensure that my vest root is always the directory of where my vtest config lives and again this is probably the more appropriate solution because it lines up with how vest actually works so in the end my day was kind of ruined because I wasn't going to make my first open source contribution turned out there was really nothing to fix and all I had to do was change my vest config so dang that was pretty much it or was it this plugin was looking for a config file named vest. config but the current config file was named vconfig and according to the vest docs vest should support both it was time the shift gears and add support for the vconfig file so back to reproducing I was able to reproduce the V config file not getting picked up then it was time to get into fixing I dug into the code I was able to find where the vest config was getting picked up so I updated the glob to pick up the V config file in addition to the vest config file and I updated the following code to return the V config file if it was found and back to our goal we want to align with how v test actually works so following the Precedence rules called out in the vest docs I adjusted the code so that the vest config file takes precedence over the V config file so I went ahead and manually tested these changes and they worked the V config file was picked up now that I verified the fix I decided to refactor the code a little bit make it much more fun and intuitive and overall I felt pretty good about it but for my first open source contribution I really didn't want to have any friction and I also wanted to be super confident about these changes and without writing any tests for this new Behavior I was probably going to get steamrolled on the pr and I wasn't very conf confident that all the scenarios work and all of the Precedence rules worked there was no automatic regression on these changes whenever future changes come in to the plugin and worst case scenario the plug-in maintainer would have to go in and manually test it and it's a pretty common talking point that it's pretty rough out there for open source maintainers sometimes so I had to get these tests running locally and I had to make sure that I had tests for my changes so I still had issues trying to get the test to run but did some research on whatever this L test Runner was and eventually got it working and now came the hard part how was I going to test my changes and this was especially tricky because I knew that my changes directly interfaced with the file system so I was a little bit hesitant to write a test against the file system but looking further into the test I realized that they're not really unit test they're more like end to end tests or I guess integration tests in this case I don't really know whatever you want to call it but anyways yeah I decided that we should definitely have these tests into interact with the file system so that we have the most confidence that the plug-in is actually working in a real environment so these tests were actually run against the example project that we had tried out earlier but I didn't want to completely clutter this example project so I created a config directory within the example project which contained a bunch of different subfolders with different V and vest config setups and with that I was able to write a couple tests that made sure the V config file got picked up the vest config file got picked up and that the vest config file had precedence over the V config file and I was able to use these changes in the example project for manual testing too which at this point didn't really matter but it was nice to make sure it really worked just as a sanity check so with that we were all good I committed the changes pushed those up to my Fork opened up a PR to the plugin from my Fork wrote up a nice PR description that's one of my pet peeves at work too I really like to have good PR descriptions that talk about things like the description the motivation behind the change as well as how the change was tested so this was a win we opened up a PR but at this point all I could do was wait so the next morning I woke up checked my email right away to see if my PR had been merged and it actually was and even better I got a nice little appreciation comment for actually writing tests so I was really excited with how fast I got merged not that my change was very big at all that was a really small change so I guess that was expected but everyall that was a good first issue for me I haven't worked with Lua much haven't done much open source in general and it was small issue that was clearly an issue which leads us into the takeaways here so these are things that you can apply to your own open source Journey so the first thing is to go in with an open mind so don't force it because you might find something else that's actually an issue along the way and we saw that exact scenario here so I went in thinking I was going to fix this plug-in in terms of making it work in monor repos turns out that wasn't even an issue but instead we found another issue where the V config file wasn't getting picked up the second takeaway here is that the best open source projects to contribute to are open source projects that you actually use there's a higher chance that you understand the domain that you're working in and understand the system as a whole that you're trying to contribute to so this kind of goes back to the idea of not forcing it let those open source problems come to you through the open source software that you use and this depends too right I think this is good advice for people who are new or getting into open source because it can be really overwhelming and probably doesn't make sense anyways to try and search out an open source project to contribute to that you don't even use and then try and fix issues in that project that you're not even familiar with and the last takeaway here is just a summary of the steps I went through and the steps I'm going to go through on future open source contributions so use op Source software find issues in that software Fork the repo get it running locally reproduce the issue locally try and fix it with test maybe even test driven development whatever you feel like open a PR from your fork write a stellar PR description and then simply wait and try and get it merged so thanks for listening hope you enjoyed this story and hopefully these takeaways inspired you and are something you can apply to your next or first open source [Music] [Music] contribution

Channel: SingletonSean

Views: 2,732

Keywords: open, source, software, web, oss, neo, vim, test, vitest, pull, request, git, github, how, to, contribute, project, runner, ide, text, editor, description, inspire, lua, script, unit, integration, changes, motivation, fire, repository, fork, primeagen, theprimeagen, prime, init, mono, repo, dirname, javascript, typescript, vite, config, configuration, local, function, tmux, terminal, command, working, directory, jest, nvim, website, api, application, programming, engineering, engineer, develop, developer, microsoft, linux, ubuntu, dotfiles, zsh, help, webcam

Id: M2eZYsKBzV8

Length: 12min 27sec (747 seconds)

Published: Thu Apr 04 2024