New guide section on Git and GitHub

[Rainer Müller]

On 2018-04-13 15:31, Jonathan Stickel wrote:
> As a long time contributor of patches using the ticket interface (Trac),
> I think it would be a mistake to discourage submission of patches there.
> While it is fine to encourage use of git pull requests, the barrier of
> entry is much higher. In fact, I just made my first pull request this
> week, and, after a nontrivial amount of effort, I still managed to mess
> it up. Git is quite powerful for sure, but it definitely has a learning
> curve. Pull requests makes use of multiple layers of abstract concepts
> (forks and branches) and multiple steps.
> 
> I think it would be reasonable to expect casual users to still upload
> patches to trac, which then port maintainers ought to turn into PRs. My
> 2 cents.

Maybe we could revisit the idea that once existed way back with the
MacPorts Web Application, but was never realized: a 'port submit' action.

I envision it to work like this:

$ port submit <Portfile>
or:
$ port submit <portdir>

The second form would only be needed when also updating patches.
This would use credentials stored in Keychain (a GitHub API auth token),
which would be asked for when used for the first time, guiding the user
through creation of such a API token that has the necessary scope. Of
course there should also be commands to delete them again or use
different credentials.

1. Run 'port lint' on the given port, stop on errors
   On warnings, ask for confirmation or require a --force option
   to continue
2. Get path from the Portfile as <category>/<portname> (PORTPATH)
1. Create a new unique branch name on "<user>/macports-ports" (BRANCH)
2. Update BRANCH to the latest master of macports/macports-ports
3. Commit new Portfile to PORTPATH in BRANCH
   Ask user for a commit message, if implemented with a temporary
   shallow clone, can just launch 'git commit --verbose'.
4. Open URL of new commit in browser, ask user to review and confirm
5.1 If confirmed, open a pull request against macports/macports-ports
5.2 If not confirmed, delete BRANCH

Rainer