WordPress Function Documentation Progress

New Documentation causes old Patches to go stale

The issue is that the line numbers will no longer match up and DIFF does not take similar lines in account all of the time. It will on your own system, since it knows what you added and can apply you additions back after it commits other changes from head. Doesn’t always work, but works often enough. The problem with patches is that they are a snapshot and don’t update.

The recent phpdoc style documentation that has been added to a lot of files, will cause a lot of previous patches for those files to go stale. While I believe it is better to have the inline documentation, than to make sure that all patches are able to be committed. I think it does put an burden on those who submitted patches and have to do so again.

I’m potentially sitting on many files which, if they were committed would break almost all of the wp-includes patches. However, if all of my patches were committed, it should only be a one time event.

I just realized this after I had my patches go stale, not from documentation, but from another mass change. I didn’t realize that it had a potential to affect many people people than myself. However, I’m sure documentation will help more people than it will hurt. It shouldn’t be that difficult to resubmit stale patches from old patches. If too much had changed, then the patch was already stale.