Establish Development and Contribution Guidelines

[shelhamer]

This is a request for comments on the Caffe development model and contribution protocol. These aren't draconian laws so much as guidelines so we can all happily brew Caffe. Establishing protocols is only a side effect of having such thriving development, so it's a lovely problem we have.

Development workflow proposal:

• master is golden.
• work is done in feature branches. These should be rebased to the tip of dev to avoid drift–and this is required for merge.
• dev is the branching point for features, and the target of pull requests for merge.
• contributions are shepherded from dev to master by the project maintainers after integration and testing via merge.
• the history of dev is not rewritten. accidents are fixed by reverts.
• "releases" are marked with tags

Contributions/Issues/PR proposal: see #101 (comment).

The closer your contribution follows these suggestions, the less friction for merging.

[Yangqing]

sounds good to me. Will help avoiding problems in #100 :)

Yangqing

On Wed, Feb 12, 2014 at 5:40 PM, Evan Shelhamer notifications@github.comwrote:

How about making a dev branch to use as the default target for pull
requests? Once there has been review and testing and the development of a
particular change has quieted down we can merge to master.

Reply to this email directly or view it on GitHubhttps://github.com//issues/101
.

[shelhamer]

Done, with a draft contributing guide in README too. 59cdf12

[shelhamer]

Let's try the dev model.

If the overhead of having dev proves annoying, we could keep up our active development in master but tag whenever we have anything "stable" enough for cloning.

[sguada]

Yeah, I'm not sure what is the best way to go. Having two parallel branches could be annoying to keep in sync but could allow to try more things. Maybe we should have someone assigned to do a code review before any pull request is merged in master.

[shelhamer]

Based on today's d339d24 breaking master (sorry everybody!) I think dev is worth the slight overhead. There are tricks to keep the integration work down.

I volunteer to handle dev for now and I'll write up a guide on working with it without headaches.

[sguada]

@shelhamer I have created my first PR #125 against dev instead of master, I hope this will work.

[shelhamer]

Here's a sketch of my proposal for a contribution protocol:

• 0. make issues for bugs (label: bug) , tentative proposals, and questions (label: question).
• 1a. make PRs as soon as development begins. create a feature branch, make your initial commit, push, and PR to let everyone know you are working on it and let discussion guide development instead of review development after-the-fact.
• 1b. As soon as a proposal from step 0 earns enough interest to warrant development, make a PR, and reference + close the old issue to direct the conversation to the PR.
• 2. when a PR is ready, comment to sign off on it and let maintainers know.

[kloudkl]

@shelhamer, I opened PR #126 to follow the clause 1a of your protocol. I believe that it will improve the development speed and the quality of the final algorithm.

[mavenlin]

@shelhamer attaching a pull request to an issue is possible with some shell scripts. http://stackoverflow.com/questions/4528869/how-do-you-attach-a-new-pull-request-to-an-existing-issue-on-github

[shelhamer]

Yes, you can attach a new PR to an issue by many ways: the API, referring
to the issue number in commits (like in my custom merges), and so on. What
I am trying to avoid is a proliferation of PRs and issues when one would
suffice, and the API does not yet support updating existing PRs.

Thank you for the script pointer though, and being conscientious in your
own work to link follow-up issues and PRs to avoid losing the thread.

Le mardi 18 février 2014, Lin Min notifications@github.com a écrit :

@shelhamer https://github.com/shelhamer attaching a pull request to an
issue is possible with some shell scripts.
http://stackoverflow.com/questions/4528869/how-do-you-attach-a-new-pull-request-to-an-existing-issue-on-github

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/101#issuecomment-35455511
.

[shelhamer]

P.S. hub is wonderful and everyone should use it.

Le mardi 18 février 2014, Evan Shelhamer shelhamer@imaginarynumber.net a
écrit :

Yes, you can attach a new PR to an issue by many ways: the API,
referring to the issue number in commits (like in my custom merges), and so
on. What I am trying to avoid is a proliferation of PRs and issues when one
would suffice, and the API does not yet support updating existing PRs.

Thank you for the script pointer though, and being conscientious in your
own work to link follow-up issues and PRs to avoid losing the thread.

Le mardi 18 février 2014, Lin Min <notifications@github.comjavascript:_e(%7B%7D,'cvml','notifications@github.com');>
a écrit :

@shelhamer https://github.com/shelhamer attaching a pull request to an
issue is possible with some shell scripts.
http://stackoverflow.com/questions/4528869/how-do-you-attach-a-new-pull-request-to-an-existing-issue-on-github

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/101#issuecomment-35455511
.

[sergeyk]

I will add a "contributing" doc page as part of #151

[shelhamer]

The README now has contributing, documentation, and branching sections and the documentation has development guidelines. This issue is solved, and further work can refine these guides.