So I’ve come to the point where I’ve wanted some to see some features on the software I regularly use and I feel confident enough that I can pull it off. However, once I start getting into it, it all becomes so overwhelming that it’s hard to get anything done.
For instance, on more than one occasion I had trouble getting the projects to build on my machine (eg., unsupported OS, lack of documentation, etc.) and it left me unable to write a single line of code making the experience frustrating from all the time wasted that I had to move on.
Other times, I recognize some the patterns and get the general gist of some snippets, but the overall code seems so convoluted to me that I don’t even know where to start to analyze a solution, even though if it’d probably take ten lines to implement.
For context, I’ve been more of a hobbyist programmer for the great majority of my life with a bit of schooling. I do have various finished apps under my belt so I’m definitely not new. But I have no reference for how long a feature should take to implement in someone else’s code for the average Joe who does this for a living.
So I’m left wondering: What advice do you have that could make this all more accessible to someone like me? Do you have a general strategy to get started? How long does it take you from start to finish? And if you run into issues, where do you seek help without nagging the devs about their code who may take too long to respond to be of use?
Many thanks for the feedback in advance!
Some tips:
- Unless the code is very small, or your feature is very big, try to put blinders on, and focus only on the code you absolutely need to to get your feature built. Use search tools to comb through the code to find the relevant methods while reading as little surrounding code as possible, tweak those methods to be different, and call that a first draft. If the maintainer wants the code refactored or differently arranged, they can help with that as part of the review process
- Being unable to build sucks, it really does. But if the software is released for your platform, it means someone out there is able to build it. And these days that someone is often an automated build tool that runs per release. See if you can figure out how this tool works. What build steps it uses, what environment it runs in, etc. If you can’t figure that out, try contacting the person who releases the builds
- If the software is in apt (if you’re on a Debian-based system), you can use
apt build-dep,apt source, anddebuildto try and recreate the native apt build process. These tools will give you the source that built the system package, and its dependencies, and allow you to build a deb yourself out of it. Test the build to make sure it’s working as-is. If it is, and if the software’s dependencies haven’t changed too much, you can even use apt to fetch the old version that’s in the repos, update the code to reflect the upstream release, and then test the build there to see if it still builds. If so, now you have something you can start working off. - If you aren’t on an apt system, but do have a package manager, I assume there’s an equivalent to the workflow mentioned above
- If your change is subtle enough that you think it’s pretty low-risk, you could just edit the code even though you can’t build it. This might be sufficient for bug-fixes where you just need to check something is greater than zero, or features where you pass a true instead of a false in certain conditions or something. You should probably mention this in your PR / MR / Patch so the reviewer knows to test building it before merging.
- This one is a bit wild, but let’s say you’re on a Mac or Windows machine, and the build instructions only work for Linux. You can just run a virtual machine that’s got Ubuntu or something running on it, and use it as your build environment. These days you can probably be in a simpler situation with Docker or something more lightweight, but as a worst-case scenario, a full virtual machine is there for you if you need it
- And finally, if the tool isn’t a crazy popular or busy tool, it’s possible the maintainer or other people in the community are more approachable than you think. If they are looking for contributions, then getting a willing contributor’s build environment setup is a benefit to the project. Improving their build docs helps not just you, but potential future contributors as well. A project will usually be more helpful towards someone who says “I’m trying to build this feature, but I’m running into trouble” compared to someone saying “why doesn’t your tool do X”. You may need to be a bit patient, they’re probably doing this on volunteer hours, but they might be happy to help you get your stuff sorted out
Good luck out there, and try not to be discouraged!
You’ve said everything actually.
- Fork
- Build (and if you can’t, stop because it will be too painful)
- Learn the code, debug, and write at the same time
- Write a merge request
That’s it. If you’re not a professional it will be longer but the steps are the same.
The only advice would be to learn your tools, learn the IDE, learn to debug. And if there is no documentation, write it.
Depends on the project (and the maintainers), but have you reached out to the developers for assistance?
Touching a foreign codebase is always difficult, even for professional coders. I have found that it usually is a very hard slog for a few weeks or so, and then it will start to click in place. I think the only real shortcut is to ask for help and see if an existing dev can guide you through it.
Agree! And if the devs are responsible enough, not only should they guide you but also improve the existing documentation/wikis, because a build issue or a doubt about anything unclear that affects one person who speaks up can potentially be affecting a lot of other people who do not even dare to ask.
Most of what comes to mind has already been said by others, but I want to add one thing…
the overall code seems so convoluted to me that I don’t even know where to start to analyze a solution, even though if it’d probably take ten lines to implement.
One of the most important things to understand about software development is that (outside of small hobby projects) the vast majority of the work is not writing code. Most of the hours will be spent on a combination of other tasks, including:
- Understanding the desired behavior
- Understanding what has been tried before
- Understanding what has and hasn’t worked well in past attempts
- Considering unexpected ways in which the software might legitimately be used
- Imagining needs that might emerge in the future
- Imagining problems/circumstances that might emerge in the future
- Devising a solution that you think will work well
- Predicting limitations of your design
- Communicating the reasons and goals behind your design choices
- Listening to feedback from others, and understanding it
- Collaborating with others to find common ground
- Conducting research to prove your assumptions or answer open questions
- Learning the ins and outs of surrounding code that is only tangentially related to yours
- Learning unfamiliar tools
- Learning unfamiliar languages
- Learning unfamiliar algorithms and data structures
- Revising your design
- Coming up with succinct and clear names for things
- Testing your implementation (making sure it works now)
- Devising and writing automated tests for your implementation (making sure it will keep working when someone else changes something)
- Composing comments to explain why non-obvious things are done a certain way
- Reformatting your code to fit the style of the project
- Writing documentation, and rewriting it
- Answering questions
- Waiting for others to get back to you
The time and effort required for all of this multiplies when modifying an existing codebase, and multiplies again when most of that code was written by other people. Shepherding a contribution from idea to final merge often requires not only technical skill, but also study, diplomacy, empathy, and immense patience.
But I have no reference for how long a feature should take to implement in someone else’s code for the average Joe who does this for a living.
It varies quite a lot. I have had dozen-line changes take months, and thousand-line changes take a day or two. Just know that if it’s taking much longer than you expected, that is completely normal. :)
Hear, hear! I would add that it multiplies again, again when other people are actually using the product. Engineers famously build tools for engineers which can leave something to be desired for the layman.
Looking back on my career, submitting your first merge/pull request can take anywhere from a few hours to several weeks (we’re talking about 8+ hour work days). And that’s at companies that have an onboarding process and coworkers you can ask for help and explanations about the code base, architecture etc.
Getting into someone else’s code (this may include your past self) is almost never easy and often feels convoluted, because it’s very difficult to see the context that existed at the time when the code was written. And by context I mean everything that influenced the decision to write lines the way they were written, including undocumented discussions, necessary but non-obvious workarounds, understanding of the problem and solution space by the dev, general state of mind of the person writing the code and more.
Don’t beat yourself up because you couldn’t contribute in just a few hours.
I would first reach out to the devs on IRC/Discord/Matrix and express interest to contribute and see how they react. You don’t know if they would even accept your PR, so I wouldn’t do too much work upfront.
Then, when they are open to work with you, find out if they are willing to help you ease into the code. What files should you study to implement the changes that you’ve discussed earlier, any considerations that are not obvious, is there legacy code that you shouldn’t touch etc.
It’s important to keep in mind that (collaborative) software development is more than just being able to write code. And a lot of the surrounding work is not very glamorous or fun.
I hope that helps and wish you good luck! 🤞
Honestly, I run and gun. I make the change I want, and submit a merge request. I then move on. It’s then up to the maintainer to accept or reject it.
I’m not going to debate it. I’m not going to rework it over the course of months to make it perfect in the maintainer’s eyes. I don’t care enough about it. I’ve solved my problem. I’m just sharing it for others.
The things I submit are normally big fixes with the smallest possible code change, not refactorings to solve an underlying problem.
Out of curiousity, whats your success rate?
I dont think there is anything wrong with that, as long as you are setting the expectations right. In some ways, it takes the load off the maintainer, because they dont necessarily have to “fix” your code, they can just rewrite from scratch using your code as inspiration.
Not high. It tends to result in one of a few things.
-
They take the fix as offered. Probably it’s a smaller quiet project where the number of PRs is small. That, or very well run.
-
It remains forever open and gets lost in the masses of other out of date PRs. Maybe a bot comes along and closes it as stale. Biggest group, and these ones just tell me that I’ve got very little chance of getting the maintainer’s attention. I can see that 100s of others have experienced the same fate.
-
Somebody else finds it useful and adopts it, fighting for it to go in. Sometimes that someone is the maintainer. As you say, it can be inspiration for a rewrite of my contribution. That’s fine by me. Whatever works.
-
The maintainer makes a bunch of rework demands leading to rejection, or it gets rejected straight off. “My way or the highway” is always going to be highway. I offered a small piece of help, and if it’s not wanted I’ll happily go away.
Maybe 20% get in, but it depends on so many things.
-
Fork it, improve it, get in they discord, cause general disarray, leave
Fork it, improve it, get in they discord, cause general
disarraydiscord, leavesmh
Boring
Can’t code. Donate to Asahi Linux on Patreon.
I’m doing my part!
Donations
Follow up question – I’m not OP but I’m another not-really-new developer (5 years professional xp) that has 0 experience working with others:
I have trouble understanding where to go on the spectrum of “light touch” and “doing a really good job”. (Tldr) How should a contributor gauge whether to make big changes to “do it right” or to do it a little hacky just to get the job done?
For example, I wanted to make a dark mode for a site i use, so i pulled the sites’s repo down and got into it.
The CSS was a mess. I’ve done dark modes for a bunch of my own projects, and I basically just assign variables (–foreground-color, --background-color), and then swap their assignments by the presence or absence of a “.dark-mode” class in the body tag.
But the site had like 30 shades of every color, like, imperceptibly different shades of red or green. My guess was the person used a color picker and just eyeballed it.
If the site was mine, I would normalize them all but there was such a range – some being more than 10-15% different from each other – so i tried to strike a balance in my normalization. I felt unsure whether this was done by someone who just doesn’t give a crap about color/CSS or if it was carefully considered color selection.
My PR wasn’t accepted (though the devs had said in discord that i could/should submit a PR for it). I don’t mind that it wasn’t accepted, but i just don’t know why. I don’t want to accidentally step on toes or to violate dev culture norms.
I’ve done a lot of development professionally, but not submitted to an OSS project, so take this with whatever sized grain of salt you deem adequate.
How should a contributor gauge whether to make big changes to “do it right” or to do it a little hacky just to get the job done?
I’d start small at first - especially if you haven’t contributed before. If you dump a huge PR on somebody then that takes a lot of effort to review, verify, test, etc. It might be easier to get acceptance by starting smaller so that it’s easier for people to understand what you’re changing and to get buy-in for the new direction. Linus Torvalds has historically been very critical of huge patches due to the amount of work it takes to verify them.
My PR wasn’t accepted (though the devs had said in discord that i could/should submit a PR for it). I don’t mind that it wasn’t accepted, but i just don’t know why. I don’t want to accidentally step on toes or to violate dev culture norms.
That’s kinda crappy - they should at least tell you why they don’t want your changes.
I agree. Light touch until you have a bunch of changes landed.
I was a professional open source contributor for a while. Still have the same job, but the license changed. Culture still quite similar though.
Different devs accept different things, and we are all burnt out to some degree.
I think you probably want to start small, i.e, normalise the colors first, and then do your dark mode change, but it really depends.
Did the dev not say why they rejected it? Seems very rude of them not to give a reason.
How should a contributor gauge whether to make big changes to “do it right” or to do it a little hacky just to get the job done?
When you work in enough diverse codebases, with enough diverse contributors, you begin to understand there isn’t one objectively right way. There are many objectively wrong ways to do something. Picking a way to do a certain task is about picking from tradeoffs. A disturbingly common tradeoff is picking rapid development over long term maintainability, but that isn’t not the right way to do it in a competitive space.
Needs change over time and certain tradoffs may no longer apply. You’re likely to see better success making lots of little hacky fixes until it’s not a hack anymore because you’ve morphed it slowly over time.
Version control, git et al, allows you to make multiple commits in a single PR, so you could break the changes up to be more reviewable.
To make it more accessible
- create your own (small) projects
- make small contributions where it’s possible (skip compiling, or -> 3.)
- try to work on a project, and quit early if it’s not simple
- pick technologies that are simple to set up or you are familiar with
When a library I’m using at work doesn’t have a feature I want or has a subpar implementation for my use case, I often try to send my changes upstream. Sometimes they get accepted, sometimes they’re too specific of a usecase.
Testing is also very useful. If you even just happen to find some bug, that you can reproduce, it’s pretty useful.
I personally have quite a few open source projects (mostly gamedev related, some are multi-purpose enough for other things), all of which need a lot of testing, also I would use someone to develop Mac (and maybe FreeBSD) parts of my middleware.
