Good question. I know that many Drupal shops have their own rules about documenting patches and hacks, but other than that, I have not seen a convention or standard.
That said, the methods I have seen in various organizations do have some common characteristics. Below are some guidelines that come to mind. Note that these are only meant for non-security patches. If you're fixing a security problem, never store the patch in a publicly accessible place (ie. under your web root) and do not submit the patch in the issue queue but report a security issue instead.
- Have a single directory with an understandable name where all patches and their documentation are stored. For instance
/patches
or /sites/all/patches
.
- Add the patch file, stored in the patches directory, to your version control system. If you didn't download a patch, but edited some code yourself, create a proper patch file and add it to your version control system.
- If you wrote the patch yourself, submit it in the appropriate issue queue on drupal.org so it can be reviewed and committed by the project maintainer.
- Create in a text file, eg.
/patches/patches.txt
, and write down:
- What has been patched
- Why the patch was needed
- A link to the issue on drupal.org where you found the patch (or submitted your own).
- When committing all of this to your version control system, write a clear commit message (you always do that, right?) that indicates that you are committing a patch.
IMHO when a developer starts working on a site he didn't build himself, he should always be aware that some code may have been patched. If you use the points above as guidelines your own documentation method, other developers should have no problems in finding out what you patched and why you did that.