Patchfile naming guidelines (was: Re: [31766] trunk/dports/audio/libao)

[Ryan Schmidt]

On Dec 11, 2007, at 15:51, Weissmann Markus wrote:

> On 11.12.2007, at 19:28, Ryan Schmidt wrote:
>
>> On Dec 8, 2007, at 02:30, Landon Fuller wrote:
>>
>>> On Dec 6, 2007, at 3:37 PM, Ryan Schmidt wrote:
>>>
>>>> Don't change this now, but remember for next time that the first  
>>>> revision of a given port version is 0, not 1. In the future,  
>>>> just remove the revision line when upgrading a port's version to  
>>>> get the default revision of 0.
>>>
>>> The default is helpful (I use it), but what's -wrong- with being  
>>> explicit?
>>
>> Nothing's wrong with specifying "revision 0", certainly. It's just  
>> not necessary. Mostly, I was pointing out that the revision should  
>> have been 0, not 1.
>>
>>>>> -patchfiles       patch-AU-configure patch-AU- 
>>>>> src__plugins__macosx__ao_macosx.c
>>>>> +patchfiles       patch-configure
>>>>
>>>> Patchfiles should be named "patch-whatever.diff". See "port lint".
>>>
>>> I guess the same question here. Is there really something wrong  
>>> with not using the .diff extension? These patches match the  
>>> original naming guidelines, but they were just guidelines.
>>
>> I've addressed this before, but my objection is that files should  
>> be named with an extension that identifies their content.  
>> Nevermind if you think filename extensions are a good or bad idea  
>> in general. On Mac OS X, they're a good idea, because you can  
>> associate files with programs based on the file's extension. If I  
>> want all diff files opened in TextWrangler, which I do, then I  
>> want to be able to inform the OS of that. If you don't name the  
>> diff files with a consistent extension (e.g. .diff), I cannot do  
>> this.
>>
>> Furthermore, TextWrangler performs syntax highlighting based on  
>> the filename extension. If you call a file patch-AU- 
>> src__plugins__macosx__ao_macosx.c, TextWrangler thinks it is a C  
>> file and tries to syntax-highlight it as a C file. But it is not a  
>> C file. It is a difference of two C files. These are not equivalent.
>
> There are two kinds of files in the files directory: Patches and  
> other files. Patches are prefixed with "patch-" which makes it  
> obvious that they are patches already.

To the best of my knowledge, Mac OS X cannot assign a file to an  
application based on a filename prefix. It can only do so based on a  
filename extension.

> And for viewing them: How do you highlight diff files?

Currently, TextWrangler uses no syntax highlighting on diff files.  
This is better than the incorrect syntax highlighting that could  
result by trying to highlight based on the rules of the diffed file.  
There is such a thing as a multiline comment, or a multiline string.  
It's possible a diff might include either the opening or closing  
quote or comment mark, but not the other one, which would result in  
chaotic highlighting. I have seen this before.

In the future, I might write my own syntax highlighting rules for  
diff files which could, for example, color lines beginning with a +  
or - in green and red, respectively, similar to what we see in the  
Trac repository browser or the commit mails.

> If they are C diffs you could highlight them as C code and if they  
> are Python diffs you can highlight the Python keywords. Your  
> argument actually speaks against the redundant ".patch" extension.

Really, we have already had this discussion:

http://lists.macosforge.org/pipermail/macports-dev/2007-October/ 
003150.html

I'll say it again: the difference of two C files is not a C file.  
(Just try compiling it.) The difference of two Python files is not a  
Python file. (Just try running it through a Python interpreter.)  
Instead, a difference is a diff file, formatted in standard diff  
format. Hence, one should use the .diff extension.

To the earlier comment that the old guide said to use "patch- 
whatever", in fact, the old guide said two different things. In one  
place, it said to use "patch-whatever" but in another place it said  
to use "patch-whatever.diff". My earlier request was to pick one  
recommendation. And for the reasons I outlined, then and now, I  
recommended that we should use the .diff extension. This was agreed  
to (at least by jmpp) and "port lint" was updated to include a check  
for misnamed patch files.