4

Let's say I had to patch a core of some module, for some reason that doesn't matter here. Is there any custom, or convention of informing future developers about it? So they will be aware of it and this may stop them from updating this module without thinking? Like creating a text file in root directory named "core-hacks" or "important-info-for-maintainers"? I have many ideas but is there any common one? Or if there is not, what would you consider the best? (the last one is open question, so you can discuss in comments).

Added: I'm considering just creating a directory in root when I will describe what I did and put applied patch, but I'm not sure if this is best what I can do, or if someone may overlook it.

Improve this question
4

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.

Improve this answer
5
  • By the way, Aiias makes a good point in his answer. You should take extra care when you're fixing a security hole, and avoid that the issue get know publicly before the fix is released officially.
    – marcvangend
    Mar 16 '13 at 22:03
  • 2
    Isn't having a file documenting the patches in a directory under the document root a security issue? Everybody would be able to read that file.
    – apaderno ♦
    Mar 17 '13 at 11:11
  • 2
    What @kiamlaluno said. This is a great answer but you shouldn't keep details of patches in the web root, they should be kept somewhere safe
    – Clive ♦
    Mar 17 '13 at 11:58
  • My comment meant to say the same: Do not document security fixes in a publicly accessible place. In my experience, you'll need to apply non-security patches much more often than security patches. The guidelines above are meant for regular bugfix or feature patches. I'll update the answer to make that clear.
    – marcvangend
    Mar 18 '13 at 8:16
  • Ok, let's all agree to a "patches.php" file in the root where changes are stored as PHP comments. Easy!
    – Coomie
    May 2 '14 at 3:43
3

Build the site from a make file.

Then you establish a single authoritative source of information on all you versions and patches.

Building the site this way, also makes applying the right patches the default action. If you rely on others to read your documentation, you will definitely have people failing this. Drush make however will always apply the patch, unless told otherwise.

Make files can also have comments, meaning there's a natural place to document why the patch is there. This comment should ideally include a a link to a d.o issue.

More info on drush make

Improve this answer
4
  • I do like this approach, but I don't think you can call it a convention (which is what the OP is asking for). Using a make file does not necessarily inform other developers about the patches you have committed, since the resulting codebase does not contain the make file itself. Using a make file can be part of the solution but it doesn't solve all problems.
    – marcvangend
    Mar 17 '13 at 19:22
  • I think it's as close to a convention as one can get. Using a package manager that declares dependencies is very common in development. It does "inform" others, if you build from a make file. I don't version control core/contrib modules. Using a makefile as just documentation isn't anywhere near as useful as using it as a blueprint is.
    – Letharion
    Mar 17 '13 at 19:56
  • 1
    I think it would be even closer to a convention if you have a way to inform any developer about the existence and location of that make file. If someone asks me "Here is a Drupal site, can you update core for me?", I should at least be able to figure out that there is a make file which may include patches, and how to obtain it.
    – marcvangend
    Mar 18 '13 at 8:34
  • It's a pretty strong convenction that one should have a VCS. If in this VCS one does not store contrib/core code, but custom code and a make-file, then it's going to be extremely hard to miss the make-file when you're updating Drupal, because there's no core to actually update. I wonder if we're somehow talking about different things here any my answer needs clarification somehow. I'm in chat for a while if you wanna try to iron this out. :)
    – Letharion
    Mar 18 '13 at 12:17
1

Take a look at Drupal documentation for How to report a security issue.

You definitely do not want to be publicly advertising a security loop-hole you find in Drupal core or a contributed module.

Improve this answer
3
  • 1
    In this case it's obvious, but this not the case, there are situations where you need to hack some module for other reasons, like to fix some small harmless bug before it will be fixed in new released version of module if you need fix fast.
    – Łukasz Zaroda
    Mar 16 '13 at 21:46
  • If you need to fix a bug in an existing module, you can hack the module by adding the fix to it temporarily. However, you should also be creating an issue for the module maintainers at drupal.org/node/add/project-issue/MODULENAME and include your patch there. With any luck, the module maintainers will accept your patch and it will be added to the codeline :).
    – Aiias
    Mar 16 '13 at 21:50
  • Łukasz: when I know that the next version of a module or core contains a fix, I generally do not care for adding patch files. The patch will no longer be necessary when the module is updated anyway.
    – Jorrit Schippers
    Mar 19 '13 at 19:50
1

The standard we've currently adopted is as follows:

  1. In the .info file, add the suffix -patched to the version number.
  2. Ensure all patch files are present in the module's root folder

  3. Add an entry in the .info file for each patch that's applied like this:

    patches[] = name-of-patch-file.patch

All patches should also be tied to a problem report at Drupal.org. This standard means that all patches are identifiable and the reason for their being used is documented publicly (and open to discussion with the world).

Improve this answer
2
  • 1
    What do you do for core where there may not be an info file?
    – mpdonadio ♦
    Mar 17 '13 at 17:37
  • Yes, that's the hole in this approach, which I haven't needed to fill as yet. Would want something that shows up on update and status reports as a minimum.
    – Alfred Armstrong
    Mar 18 '13 at 8:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.