Inheriting an Open Source Project
During my time at Salesforce, I’ve come to love open source software (OSS).
I previously maintained Fuel UX and actively maintain the Salesforce Marketing Cloud’s Node.js SDKs (Authentication, REST, SOAP).
(From this point on I will be referring to these individual SDKs as “modules.”)
Before becoming maintainer for some of these projects, I had used them a lot. For some, I had even built them myself. I felt confident in what I was doing.
Unfortunately, I was not so familiar with the SOAP module. I’d only helped out here and there, and to be perfectly honest, I knew almost nothing about it. But, it had been modelled after the other two modules I built (Auth and REST from above), so there’s that.
Everything was going well until a few months ago. Someone submitted a pull request (PR), as they needed a feature implemented. (Good on them for the PR—often I would be asked to make code changes, but it is much more pro-active for the individual to improve the code themselves.)
As I looked at the PR, I found myself wondering about the implications of this change. Will it affect backwards compatibility? Does it actually accomplish what is needed? Are there security concerns? The list goes on. I had no clue about any of these answers because I didn’t write that module.
If you find yourself in this situation, there are certain things that can help immediately. There are also things you can do to mitigate this situation in the future. Let’s explore a few.
Read the Documentation
Like I said, I knew very little about the SOAP module. For that matter, I also knew very little about the Marketing Cloud’s SOAP API.
But thankfully, compared to companies I had worked at previously, Salesforce had a good amount of documentation for the SOAP API, which proved really useful.
To be honest, when you have good documentation, implementing small features or bug fixing isn’t too hard, even if you don’t know the big picture.
When in doubt, ask for help
After realising I didn’t feel confident making these changes, I swallowed my pride and asked a co-worker for help.
Good thing too, as I would’ve missed a small change that could’ve had a huge impact. Basically, I almost released a major change according to semver, but in a minor release. Not the best!
There’s nothing wrong with asking for help. If you don’t understand something, ask. If you think you are implementing something incorrectly, ask. You’ll learn something new, if not get validation on what you were doing.
At this point, I ask so many questions, my co-workers are probably annoyed with me to be honest!
Improve tests around existing functionality
After this PR situation, I wanted to mitigate the chances of this happening in the future.
I started by analysing the current tests, which were along the lines of fake integration tests, and found holes and general things I wasn’t happy with. New unit tests were in order. A complete rewrite.
Side note: remember I said my modules were a template for this one? Well, so were the tests. Kind of my fault!
I started using TDD at work a while ago and felt my code has become more concise and much more tidy. No accidental over-engineering. So, I tried it out on this project, with great success I think.
The whole process took a few days, but I finally got to around 100% coverage. It’s one massive PR, but a needed one. And before you start saying “coverage doesn’t matter” … let me agree with you. What matters is that you test all the functional aspects. It just so happened that when I did that, I achieved a good amount of coverage.
I am now much more confident when implementing features/bug fixing. While my tests won’t catch everything, they are a great start!
During the test re-vamp, I actually found a few bugs, which were so easy to fix due to this work.
If you haven’t checked out TDD, I would highly recommend it. It takes a little while to get used to, but I feel it’s very worthwhile in the end. I’ve put a few links below (if you have a good one to add, just comment!).
- The Failures of “Intro to TDD” — the author actually likes TDD, but thinks it’s incorrectly introduced to people
- The Three Rules of TDD — seem logical, but could be taken too far
Make the repo friendlier
We’ve all heard that some maintainers are not the nicest and even discourage new contributors from ever starting.
That’s not what we want at Salesforce. The more contributors the better.
In this vein, I’ve tried to make it as easy as possible to contribute using the issue tags on Github, writing better issues, and even including some pre-built tests for others to get passing.
It’s certainly been a journey with this module, and one that is ongoing. But using these methods, I’ve been able to progress and improve a module I was unfamiliar with.
OSS is not always easy. Contributing and maintaining a project can be difficult and complicated, but it is a practical way to learn and develop your technical skills. Good luck!!
