Best practice for managing changes to 3rd party open source libraries? [closed]

Question

On a recent project, I had to modify an open source library to address a functional deficiency. I followed the SVN best practice of creating a "vendor source" repository and made my changes there. I also submitted the patch to the mailing list of that project. Unfortunately, the project only has a couple of maintainers and they are very slow to commit updates.

At some point, I expect the library to be updated, and I expect that my project will want to use the upgraded library. But now I have a potential problem...

I don't know whether my patch will have been applied to this future release of the 3rd party library. I also don't know whether my patch will even still be compatible with the internal implementation of the upgraded components. And in all likelihood, someone else will be maintaining my project by that point.

Should I name the library in a special way so it is clear that we made special modifications (eg. commons-lang-2.x-for-my-project.jar)? Should I just document the patch and reference the SVN location and a link to the mailing list item in a README? No option that I can think of seems to be fool-proof in an upgrade scenario.

What is the best practice for this?

Answer 1

The Vendor Branches chapter of the SVN "red book" covers this well. The example in this chapter seems to match your situation closely:

http://svnbook.red-bean.com/nightly/en/svn.advanced.vendorbr.html

...
Now you face an interesting situation. Your project could house its custom modifications to the third-party data in some disjointed fashion, such as using patch files or full-fledged alternative versions of files and directories. But these quickly become maintenance headaches, requiring some mechanism by which to apply your custom changes to the third-party code and necessitating regeneration of those changes with each successive version of the third-party code that you track.

The solution to this problem is to use vendor branches. A vendor branch is a directory tree in your own version control system that contains information provided by a third-party entity, or vendor. Each version of the vendor's data that you decide to absorb into your project is called a vendor drop.
...

Answer 2

Aside from Bert's answer, which is good as far as the source control part of the question is concerned, I'd also suggest you write some unit-tests that cover your changes.

And don't get me wrong, I don't mean to say that you should just write one or two unit-tests and then forget about it. For regression testing/unit-testing to really work, it needs to be implemented systematically and it needs to become a consistent part of the project's automated building process.

And obviously, this is not easy either, once you're gone, you'll have no guarantee that your replacement/your coworkers continue using your testing strategy. So that too is something that you must document, refine, make it easier to do, and constantly educate your coworkers and management on.