New guide section on Git and GitHub

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

New guide section on Git and GitHub

Perry E. Metzger-2
I just committed a new section of the guide called "Using Git
and GitHub". Please read, comment, and improve.

Perry
--
Perry E. Metzger [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Andrew Moore
Um, submit pull requests, no?

> On Apr 11, 2018, at 5:31 PM, Perry E. Metzger <[hidden email]> wrote:
>
> I just committed a new section of the guide called "Using Git
> and GitHub". Please read, comment, and improve.
>
> Perry
> --
> Perry E. Metzger [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Andrew Moore
In reply to this post by Perry E. Metzger-2
My impression from the mailing list is that going forward Trac would be used exclusively for bug reports.  Any code submissions would ideally be submitted as pull requests to GitHub.  If so, this change needs to put front and center, in large display type.

Section 7 “MacPorts Projects” should begin:  SUBMIT CODE AS GITHUB PULL. REQUESTS.  IF YOU JUST WANT TO $#!@, PLEASE USE TRAC
-AM

> On Apr 11, 2018, at 5:31 PM, Perry E. Metzger <[hidden email]> wrote:
>
> I just committed a new section of the guide called "Using Git
> and GitHub". Please read, comment, and improve.
>
> Perry
> --
> Perry E. Metzger [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Perry E. Metzger-2
In reply to this post by Andrew Moore
On Wed, 11 Apr 2018 17:54:23 -0400 Andrew Moore <[hidden email]>
wrote:
> > On Apr 11, 2018, at 5:31 PM, Perry E. Metzger
> > <[hidden email]> wrote:
> >
> > I just committed a new section of the guide called "Using Git
> > and GitHub". Please read, comment, and improve.
>
> Um, submit pull requests, no?

Of course! If you have improvements, submit pull requests!

(But if you're asking why this wasn't done with a pull request, I
talked to the gang on IRC and was told to just straight commit it.)

Perry
--
Perry E. Metzger [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Perry E. Metzger-2
In reply to this post by Andrew Moore
On Wed, 11 Apr 2018 18:19:50 -0400 Andrew Moore <[hidden email]>
wrote:
> My impression from the mailing list is that going forward Trac
> would be used exclusively for bug reports.  Any code submissions
> would ideally be submitted as pull requests to GitHub.

That's both true and not quite true. I think ultimately we'll be
going to that but for the moment we're easing in to it. The document
currently says, in effect, "we strongly prefer GitHub pulls over Trac
for code submissions."

I figure that ultimately it will indeed say "please
only submit code by GitHub" but I don't think we have consensus on
that yet. (If I'm wrong and we do have consensus, someone should feel
free to make that even stronger in the document.)

> If so, this
> change needs to put front and center, in large display type.
>
> Section 7 “MacPorts Projects” should begin:  SUBMIT CODE AS GITHUB
> PULL. REQUESTS.  IF YOU JUST WANT TO $#!@, PLEASE USE TRAC -AM

Perry
--
Perry E. Metzger [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Andrew Moore
As someone who only reads the manual as last resort, I think Section 7 of the MacPorts Guide could be retitled from “MacPorts Project” to “Contributing to MacPorts”.  And then steps for creating pull requests via GitHub spelled out tutorial-wise.  Perhaps steal an existing tutorial.  But there are additional workflows and tricks like `git config receive.denyCurrentBranch updateInstead’ that might be worth sharing with contributors (the last trick is useful for syncing clones across multiple machines).

While I appreciate the intent, I think “easing into” GitHub is more obfuscating, and actually adds an extra hurdle for contributors.  For instance the section immediately following “Using Git and GitHub” is titled “New Ports” and proceeds with steps for contributing a Trac ticket.

Okay, so when all is said and done, am I actually prepared to make an actual contribution?  Perhaps it merits a topic of discussion for the online meeting how MacPorts wants to present itself.  I’d like to see one of MacPorts’s goals be towards non-profit status, and ultimately to attract the attention of Apple again.  Apple needs MacPorts desperately, they just don’t know it yet…
-AM
 

On Apr 11, 2018, at 6:33 PM, Perry E. Metzger <[hidden email]> wrote:

On Wed, 11 Apr 2018 18:19:50 -0400 Andrew Moore <[hidden email]>
wrote:
My impression from the mailing list is that going forward Trac
would be used exclusively for bug reports.  Any code submissions
would ideally be submitted as pull requests to GitHub.

That's both true and not quite true. I think ultimately we'll be
going to that but for the moment we're easing in to it. The document
currently says, in effect, "we strongly prefer GitHub pulls over Trac
for code submissions."

I figure that ultimately it will indeed say "please
only submit code by GitHub" but I don't think we have consensus on
that yet. (If I'm wrong and we do have consensus, someone should feel
free to make that even stronger in the document.)

If so, this
change needs to put front and center, in large display type.

Section 7 “MacPorts Projects” should begin:  SUBMIT CODE AS GITHUB
PULL. REQUESTS.  IF YOU JUST WANT TO $#!@, PLEASE USE TRAC -AM

Perry
-- 
Perry E. Metzger [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Dave Horsfall
On Wed, 11 Apr 2018, Andrew Moore wrote:

> Okay, so when all is said and done, am I actually prepared to make an
> actual contribution?  Perhaps it merits a topic of discussion for the
> online meeting how MacPorts wants to present itself.  I’d like to see
> one of MacPorts’s goals be towards non-profit status, and ultimately to
> attract the attention of Apple again.  Apple needs MacPorts desperately,
> they just don’t know it yet…

Having (re)discovered Perl/Tk I'm certainly interested in jazzing up a few
of my programs, but there's something about GitHub that bothers me (and I
don't know what); perhaps it's my general dislike of Penguin/OS and
anything spawned from it (including the GPL virus), I dunno...

--
Dave Horsfall DTM (VK2KFU)  "Those who don't understand security will suffer."
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Andrew Moore


> On Apr 11, 2018, at 7:52 PM, Dave Horsfall <[hidden email]> wrote:
>
> On Wed, 11 Apr 2018, Andrew Moore wrote:
>
>> Okay, so when all is said and done, am I actually prepared to make an actual contribution?  Perhaps it merits a topic of discussion for the online meeting how MacPorts wants to present itself.  I’d like to see one of MacPorts’s goals be towards non-profit status, and ultimately to attract the attention of Apple again.  Apple needs MacPorts desperately, they just don’t know it yet…
>
> Having (re)discovered Perl/Tk I'm certainly interested in jazzing up a few of my programs, but there's something about GitHub that bothers me (and I don't know what); perhaps it's my general dislike of Penguin/OS and anything spawned from it (including the GPL virus), I dunno…

I should clarify that I speak for myself and not for MacPorts, not being a member.  And my reference to Trac probably came across as derogatory, which was unintended.

I’m curious if your dislike extends to command-line tool git(1) or just the company built around it?
-AM





Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Mark Anderson-10
Have we thought about moving entirely to github. Using issues and projects? I remember there being a reason we didn't, but I don't remember what it was.

—Mark
_______________________
Mark E. Anderson <[hidden email]>

On Wed, Apr 11, 2018 at 10:17 PM, Andrew Moore <[hidden email]> wrote:


> On Apr 11, 2018, at 7:52 PM, Dave Horsfall <[hidden email]> wrote:
>
> On Wed, 11 Apr 2018, Andrew Moore wrote:
>
>> Okay, so when all is said and done, am I actually prepared to make an actual contribution?  Perhaps it merits a topic of discussion for the online meeting how MacPorts wants to present itself.  I’d like to see one of MacPorts’s goals be towards non-profit status, and ultimately to attract the attention of Apple again.  Apple needs MacPorts desperately, they just don’t know it yet…
>
> Having (re)discovered Perl/Tk I'm certainly interested in jazzing up a few of my programs, but there's something about GitHub that bothers me (and I don't know what); perhaps it's my general dislike of Penguin/OS and anything spawned from it (including the GPL virus), I dunno…

I should clarify that I speak for myself and not for MacPorts, not being a member.  And my reference to Trac probably came across as derogatory, which was unintended.

I’m curious if your dislike extends to command-line tool git(1) or just the company built around it?
-AM






Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Mojca Miklavec-2
On 12 April 2018 at 04:39, Mark Anderson wrote:
> Have we thought about moving entirely to github. Using issues and projects?
> I remember there being a reason we didn't, but I don't remember what it was.

Yes, we did. Ryan even had all trac tickets imported into GitHub and
some redirection from old URLs from Trac tickets to the issue.

The reason for not proceeding were too many limitations. Like,
inability to list all tickets belonging to a particular port,
inability to show all issues assigned to you, it was impossible to
enforce consistent numbering of tickets during the initial import,
people who submitted tickets would no longer be their "authors", they
would only get an email saying "discussion continues here" for each
ticket they ever participated at.

GitHub issues could potentially work well for individual components
like macports-base, but then I'm not sure if we would be ok with
having half of issues on GitHub and the other half on Trac.

Mojca
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Dave Horsfall
In reply to this post by Dave Horsfall
On Thu, 12 Apr 2018, Mojca Miklavec wrote:

> p5-tkx has recently beed added to ports and that one supports native
> look and feel :)

Now you really have me interested - thanks!

I've just spent a few hours tracking down an obscure (and intermittent!)
bug in a script that controls a serial device only to find that it's a
firmware bug, and I don't think that there's a way around it once it gets
into that state without power-cycling the thing :-(

I'll fix the fundamntals before I get the flashy stuff working, of
course...

--
Dave Horsfall DTM (VK2KFU)  "Those who don't understand security will suffer."
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Perry E. Metzger-2
In reply to this post by Andrew Moore
On Wed, 11 Apr 2018 19:30:56 -0400 Andrew Moore <[hidden email]>
wrote:
> As someone who only reads the manual as last resort, I think
> Section 7 of the MacPorts Guide could be retitled from “MacPorts
> Project” to “Contributing to MacPorts”.  And then steps for
> creating pull requests via GitHub spelled out tutorial-wise.
> Perhaps steal an existing tutorial
> <https://yangsu.github.io/pull-request-tutorial/>.

Pull requests to make these changes would be quite welcome!

> While I appreciate the intent, I think “easing into” GitHub is more
> obfuscating, and actually adds an extra hurdle for contributors.
> For instance the section immediately following “Using Git and
> GitHub” is titled “New Ports” and proceeds with steps for
> contributing a Trac ticket.

Only after saying please use GitHub preferentially in boldface and
first saying "use github! but if you're using trac, do this!"

Perry
--
Perry E. Metzger [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Jonathan Stickel-5
In reply to this post by Perry E. Metzger-2
On 4/11/18 17:31, [hidden email] wrote:

> Date: Wed, 11 Apr 2018 18:33:19 -0400 From: "Perry E. Metzger"
> <[hidden email]> To: Andrew Moore <[hidden email]> Cc:
> MacPorts Development <[hidden email]> Subject: Re: New
> guide section on Git and GitHub Message-ID:
> <[hidden email]> Content-Type:
> text/plain; charset=utf-8 On Wed, 11 Apr 2018 18:19:50 -0400 Andrew
> Moore <[hidden email]> wrote:
>> My impression from the mailing list is that going forward Trac
>> would be used exclusively for bug reports.  Any code submissions
>> would ideally be submitted as pull requests to GitHub.
> That's both true and not quite true. I think ultimately we'll be
> going to that but for the moment we're easing in to it. The document
> currently says, in effect, "we strongly prefer GitHub pulls over Trac
> for code submissions."
>
> I figure that ultimately it will indeed say "please
> only submit code by GitHub" but I don't think we have consensus on
> that yet. (If I'm wrong and we do have consensus, someone should feel
> free to make that even stronger in the document.)
>
>> If so, this
>> change needs to put front and center, in large display type.
>>
>> Section 7 “MacPorts Projects” should begin:  SUBMIT CODE AS GITHUB
>> PULL. REQUESTS.  IF YOU JUST WANT TO $#!@, PLEASE USE TRAC -AM

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.

Regards,
Jonathan
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Rainer Müller-4
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
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Perry E. Metzger-2
In reply to this post by Jonathan Stickel-5
On Fri, 13 Apr 2018 07:31:45 -0600 Jonathan Stickel
<[hidden email]> 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.

We're currently encouraging use of pull requests, not banning the use
of Trac. If you find Trac is vastly easier, then use that for now.
The price is that you may not get attention to your requests as
quickly.

Perry
--
Perry E. Metzger [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Jonathan Stickel-5
On 4/14/18 08:29 , Perry E. Metzger wrote:

> On Fri, 13 Apr 2018 07:31:45 -0600 Jonathan Stickel
> <[hidden email]> 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.
>
> We're currently encouraging use of pull requests, not banning the use
> of Trac. If you find Trac is vastly easier, then use that for now.
> The price is that you may not get attention to your requests as
> quickly.
>

Sure, it makes perfect sense to encourage PRs while continue to consider
patches. I'm not against that at all, and I'm willing to figure it out.
But care should be taken about the tone of the message, especially given
the current competition. Any perception that Macports is not friendly to
new users and contributors would be a mistake.
Reply | Threaded
Open this post in threaded view
|

Re: New guide section on Git and GitHub

Andrew Moore
On Apr 14, 2018, at 4:01 PM, Jonathan Stickel <[hidden email]> wrote:
>
> Sure, it makes perfect sense to encourage PRs while continue to consider patches. I'm not against that at all, and I'm willing to figure it out. But care should be taken about the tone of the message, especially given the current competition. Any perception that Macports is not friendly to new users and contributors would be a mistake.

Jonathan,
I’ll take the blame for the tone.  This is not my first transgression, and I apologize both to you and the MacPorts folks.
-AM