separate workflow for trusted contributor

[mjlosch]

I just talked to Nikolai Kolnudov (@koldunovn), who is quite experienced with GitHub. He said that the proposed standard workflow is great for big projects with many contributors (like scipy), but that it can be more convenient to have a workflow for a small group of contributors, e.g. like our group of CVS-contributors, that is simpler: Instead of forking, you clone the repository directly, work on your branches and then create PR from the branch on the main repository to the master. The PR would still be discussed and eventually merged by someone other than the one creating the PR, but in this way, it would be a lot easier for those who contribute a lot to keep the local clone/branches up to date, etc. In his experience the "standard workflow" can be confusing (rebase versus merge, etc.) and we would save ourselves some time and nerves by circumventing that. Also the workflow would be much more like what we have at the moment. The obvious disadvantage, it seems to me, is that there will be very many branches on the repository and we'd have the be very disciplined to delete branches after their contents and associated PRs have been merged.

[christophernhill]

@mjlosch and @koldunovn there is also a somewhat streamlined approach here https://hub.github.com - see section # Example workflow for contributing to a project:. This preserves the fork step, but makes everything CLI based and maybe less clunky. This could be a kind of middle ground? What do you think?

Note

• all the rebase, merge etc... chatter is really just guidelines. The guidelines cannot be enforced, so I think people can use whatever they think makes sense to them as long as the history looks neat, things come in as a PR and the commit passes any relevant tests and relevant review bits. Obviously its good to have some good guidelines for anyone looking for where to start.

The branches on the main repo approach seems like a route for a mess to me, but the https://hub.github.com thing is close to as easy that without the mess bit - maybe. It does require installing a small .go program on your local machine. Note

• hub.github.com does not really require the kludgey git alias the hub.github.com folks suggest, all it needs is the two Go programs that are here
  • https://github.com/github/hub/blob/master/commands/fork.go
  • https://github.com/github/hub/blob/master/commands/pull_request.go

Also

• I assume we will add some more committers as we go forward, but at the moment we are assuming that all committers would also use a fork workflow (I am using the hub.github.com tool) too.

• I also assume we will also define a little more about the test/review process. For example for documentation provided by a primary author its not clear that it really needs to wait for too much review etc...

• AND the goal is still to get into a rhythm that results in more substantive output (i.e. not just email threads!) for less effort.

[jklymak]

You may want to chat w/ @efiring about his experience as a maintainer for matplotlib. FWIW, I'm 98.5% sure that maintainers there do not keep their own development branches on the main repositories. Branches are used for new releases, so for instance 2.x can be maintained while 3.0 is being developed.

I've tried contributing a few times to matplotlib. The whole forking thing can be a pain when it comes time to make a pull request, but once you figure out how to do it properly, its relatively straightforward. Similarly, the maintainers don't like a bunch of commits in their pull requests, so you get to learn how to squash your commits so it doesn't dirty up the commit logs.

[jklymak]

Also, I'd have thought the point of going to GitHub was to get around the "mailing your diff files to the maintainer you think will have time to take a look at it" workflow. i.e. that you want more than just the CVS contributors to contribute code, but that you still want those folks to be the gatekeepers of any new code.

[edoddridge]

Thanks for starting this discussion @mjlosch! @koldunovn and @efiring - if you've got additional comments, please jump in.

Firstly, I didn't document two workflows because we wanted to test out the forking/PR workflow. This, somewhat more convoluted, workflow has a few benefits:

• all changes must come through pull requests (if a large group have write access to the main repo, we can still enforce this as a social policy, but the current setup requires it);
• there's very little chance of someone accidentally pushing changes into the master repository, or doing something silly like rebasing the master branch (only a small number of people have the access privileges to do that, and they're going to be vigilant); and
• there is no chance of stale development branches cluttering up the main repo, since they simply won't exist.

My feeling is that after the first few times, it won't feel like a big imposition - this seems to be what @jklymak is saying too. Having said that, if, in the future, we decide that it simply isn't worth the hassle, then we can expand the list of people with access to the main repo and let them all work on branches in that repo. We may expand the list anyway, since that would let people push commits onto PR branches.

The option to fork, branch, develop, and submit a PR will always be available to everyone, regardless of there access privileges in the main repo, so I don't foresee any likelihood that we will end up in the "mailing your diff files to the maintainer" situation described by @jklymak