How to document 3rd party libs modifications?

Question

Sometimes I need to modify a third party library for my specific needs. It can be bug fixes, performance improvements, adding features etc.

For instance I included JSoup and Android Support Library sources into my project and made several changes. I also did the same thing with 2 Java files from Android source code.

How should I document this?

Answer 1

Rule -1

Don't. Maintaining forked versions of libraries is painful, especially when you want to upgrade the library and need to backport your changes over and over again. Not to mention one day someone will forget about your version and use standard one.

Thus always try to include test case that fails without your change (exposing bug in external library manifesting in your code).

Rule 0

Always submit your changes to original authors/maintainers. File an issue and include your patch. If your change was worth violating rule -1, it will probably be included in next release.

Rule 1

Commit the original source files of the library without any change. Then commit every single improvement/bugfix with descriptive message. Preferably include issue/ticket id that will point to an explanation in your (or library's) ticketing system.

This way when browsing the list of commits of this given directory or project you can easily see what has been changed. If the commit message is not enough to describe the need to fork and modify the external library, you can always browse the issue/ticket. Also in an ideal world such a commit makes an ideal patch (see rule 0).

---

Bonus: I once had an idea of automating forking and patching external libraries via maven plugin. Basically we instruct this hypothetical plugin to apply given patch(es) on particular library. Maven can easily download sources, rebuild, install and include modified version automatically instead of the original one in the target artifact.

No need to maintain forked binaries, easy upgrade providing that the patch still applies cleanly on new version. Anyone having too much free time here?