Instructions for creating patches

[Rainer Müller]

On 2018-05-03 09:14, Zero King wrote:
> On Thu, May 03, 2018 at 08:51:49AM +0200, Mojca Miklavec wrote:
>> On 1 May 2018 at 16:11, Rainer Müller wrote:
>>>
>>> The guide uses "Portfile-rrdtool.diff" as an example filename [1]. Some
>>> users seem to take that literally and submit patches with that name.
>>>
>>> [1] https://guide.macports.org/#development.patches.portfile
>>
>> Looking at this part of the guide, I would suggest that we change the
>> instructions. It almost definitely makes more sense to use "git diff
>> ..." instead of "diff ...", but more importantly we probably want to
>> suggest creating a pull request at that point anyway.
> 
> Some contributors would edit the Portfile in
> /opt/local/var/macports/sources/rsync.macports.org/macports/release/tarballs/ports/,
> which isn't a git repository and `git diff` won't work for them.

If users edit the ports tree directly there is no way to diff at all and
the changes will be lost on the next sync. They should never do that.

'git diff' actually works with arbitrary paths when not inside a
repository, as it implies the --no-index flag in this case.

The mix of instructions on how to create a patch against a Portfile and
how to create a patch against upstream sources might also be a bit
confusing and I would recommend to separate that.

Maybe the instructions on how to create a local ports tree should come
first and then the next section should show how to create a diff against
the official ports tree?

Instructions on how to create a pull request would overlap with the
section "Using Git and GitHub" [1]. We should only document this in one
place.

> Maybe "git format-patch -1" is better than "git diff ..."? But that
> would be even closer to a pull request.

That also requires that the user already has a repository available.

I still think that a port action like 'port submit' [2] (or as a start
even just an external script), would help untrained contributors more
than replicating the GitHub documentation on how to make a pull request.

Rainer

[1] https://guide.macports.org/#project.github
[2] https://lists.macports.org/pipermail/macports-dev/2018-April/038318.html