The git instructions say this:

git format-patch origin/master --stdout > [description]-[issue-number]-[comment-number].patch

A lot of maintainers, myself included, put the issue number first, so [issue-number]-[comment-number]-[description].patch. It makes all patches group nicely in folder listings and for command line autocomplete you can just start typing the issue number.

I think this is the more popular format, but I appreciate this is bikeshed :)

Comments

damienmckenna’s picture

damienmckenna
Location TN, USA
commented

I keep all of my patches together, in case I need to refer to them later, so I prefix them with the module name, e.g.:

  • [module]-n[issue-number]-[comment-number]-[optional-description].patch
agentrickard’s picture

agentrickard
he/him
Primary language English
Location Georgia (US)
commented

I walked through this with some other folks recently.

I'm with @joachim, I greatly prefer number first.

If we use [module] first, can we prefix with _ so it floats to the top of file lists?

sun’s picture

sun
Primary language German
Location Karlsruhe
commented

Absolutely no idea why this issue is in this project. Just because it's mentioned in the git guide, it doesn't mean the format wouldn't be documented in detail elsewhere already.

But whatever... my 2 cents:

[project].[2-4-words-issue-summary].[comment].patch
  • The issue number is needless in >99% of all cases.
  • Always re-use an existing issue summary of earlier patches, as long as it's "valid".
  • The project name is crucial.
  • Separating filename parts with dots/periods allows to use hyphens in the issue summary and easily identify the filename parts.
joachim’s picture

joachim commented

Putting module name first makes autocomplete a *real* pain -- because everything in the foo module folder is already called foo.*.

I find issue number really useful so I know what a patch relates to (and whether I can delete the file! -- though with git that is maybe not so important).

> # Separating filename parts with dots/periods allows to use hyphens in the issue summary and easily identify the filename parts.

Agreed. My format is:

[issue]-[comment, optional].[module].description-with-hyphens.patch

damien tournoud’s picture

damien tournoud commented

The issue number is needless in >99% of all cases.

On the contrary, the issue number allows to quickly get back to the parent issue.

I am for:

[issue-number]-[optional-description].patch

There is no need for neither the module name nor the comment number in there. Drupal will append unique numbers at the end of your file itself.

damien tournoud’s picture

damien tournoud commented

Also: you cannot predict the comment number before it is actually allocated to you. Someone could very well comment before you do. Given the amount of cross-post happening on d.o, this is far from an unlikely scenario.

joachim’s picture

joachim commented

True. The other way is to just increment a number after the issue number, so [issue]-[delta].[module].description.patch. You can't predict you won't clash with someone else either but it's less likely.

agentrickard’s picture

agentrickard
he/him
Primary language English
Location Georgia (US)
commented

I agree with #5 and there is zero chance that I will EVER put a comment # in a patch file. Waste of my time.

joachim’s picture

joachim commented

> I agree with #5 and there is zero chance that I will EVER put a comment # in a patch file. Waste of my time.

What happens though is this:

1. Download person X's patch.
2. Apply it.
3. Do some further work
4. Roll a new patch.

I'm curious what your workflow here if you don't have a delta or comment number -- do you clobber the first patch file?

dave reid’s picture

dave reid
he/him
Primary language English
Location Nebraska USA
commented

I'm curious what your workflow here if you don't have a delta or comment number -- do you clobber the first patch file?

Yes. I can always re-download it if I wanted the original.

agentrickard’s picture

agentrickard
he/him
Primary language English
Location Georgia (US)
commented

Yes. Keeping patch versions straight is not a problem. If needed, I rename the patch description a bit.

moshe weitzman’s picture

moshe weitzman commented

Maybe I'm slow, but what's the benefit of a standard at all here? I get that the test bot only cares about .diff/.patch and a couple other rules. Isn't patch filenaming a (trivial) personal preference?

merlinofchaos’s picture

merlinofchaos commented

Personally, I prefer the issue number first; issue numbers are more unique than my module's name, and I have to work harder with tab complete to find the file. Whereas, issue numbers are 7 digits long and that's about the most I have to type in order to have tab complete get me the whole file.

The absolute worst patch format for me is views.module-blah-blah, I just have to work that much harder to find the file. Tab complete gets me views.module -- but only after at least two tries, since 'views.' will stop to pick up the .info file. Just a minor annoyance, I know, but for me, issue # first is best.

Issue # is always best so that when I've collected 100 patches (and I do on a regular basis) I can figure out which issue a particular patch came from.

marvil07’s picture

marvil07 commented

IMHO if you are using git anyway to produce a patch, why not let it decide the name too?

I use to put the work in one patch and then just do a git format-patch -1, in that way Git will convert the first line in the commit message(that is already something we agree on) into a filename.

joachim’s picture

joachim commented

> Maybe I'm slow, but what's the benefit of a standard at all here?

The git instructions for patching give an example filename, and therefore there is a defacto standard already whatever we do.

> The absolute worst patch format for me is views.module-blah-blah

Yes! Absolutely.

> I use to put the work in one patch and then just do a git format-patch -1

Interesting!
But that's not really going to work if you're working on a branch for the issue with lots of commits until you're ready to post a patch. When I do that, the final commit on my issue branch is usually 'Works!' or 'Cleanup' or 'Docs'...

eliza411’s picture

eliza411 commented

>> Maybe I'm slow, but what's the benefit of a standard at all here?

> The git instructions for patching give an example filename, and therefore there is a defacto standard already whatever we do.

I think the point is that we could choose not to set a standard in the instructions.

eliza411’s picture

eliza411 commented
Status: Active » Closed (won't fix)

We do set a defacto standard in Git instructions, but I don't see a clear recommendation for change, so I'm going to mark this as "won't fix."

Because this issue affects community-wide practices, if anyone's feeling motivated to pursue change, I'd like to see the conversation moved to g.d.o. where it will receive broader consideration. If/when there's a specific request, then opening a new issue would be in order and adjustments can be quickly made.

I'm not sure if the Git team's group site has broad enough membership to reach all the folks who care about this issue, so if someone does open a g.d.o. discussion, please post the link back here so interested folks can find it.