git (how to contribute code to OF)

After 007 we are going to use a new development model in git.

The master branch will always contain the current stable release.

The develop branch will contain the latest changes that will go in the next release.

To contribute code, take a look at this page in github:

https://github.com/openframeworks/openFrameworks/wiki/openFrameworks-git-workflow

but basically, never send pull requests to/from master, but to/from the develop branch, and use separate branches in your forked repository, with names like feature-* or bugfix-*, to contain your contributions.

I’m going through the links on that page, trying to learn git.

this page http://help.github.com/fork-a-repo/ says I should fork the repo that I want to contribute to. Is that necessary or should I just start by doing a git clone on the main oF repo?

After that, the steps are to make a feature-* or bugfix-* branch locally to work on something, then pull from oF into my local version to see if everything merges properly, and then send the pull request to of for review. is that right?

You should fork the repo. This has the advantage, that you can clone your fork, work on it and upload your changes. Then you can easily do a pull request via the github site.

If you simply clone the main OF repo, then you’d have no way of uploading your changes. Because the repo is read only (at least for most people).

Ok, that makes sense. Now how do i make sure that my fork stays up to date with the main of development branch when others submit changes?

When you checkout your new fork and run “git branch”, you should have an output that that tells you something like this (but Tim instead of underdoeg :wink: ):

  
  
  master  
* underdoeg/master  
  

The master is the openframeworks master, so now you can run “git pull origin master” to get a local update and then “git merge origin master” to merge those changes with your local branch.

underdoeg, I think this is only partly correct.
when you clone your own fork, your github repo gets added as a remote called “origin” (which is the way it should be because you have write access only there). you then should add the github read-only url (from the github page) as another remote (“upstream” is a good name).
then the rest is as you say. you “push/pull origin master” to/from your own repo.
for staying up to date with oF, you do git pull upstream master, and git merge upstream master - make sure you’re in the correct branch (master) before doing that, though - check with “git status”.

Bilderbuchi, your explanation does indeed sound like the correct way to go. But in my case the upstream was somehow added automatically I think? I thought github had some automated mechanism or something going on there. But it’s also very possible that I added origin and upstream manually and forgot about it… ::slight_smile:

hm, both is possible. as far as i know, on “git clone”, the repo you’re cloning from is automatically added as origin. don’t know about automatically adding upstream - maybe github is getting even smarter, and doing this too, now?
in any case, the “usual” nomenclature is to call your own remote repo (where you also have write access) “origin” and the repo you originally forked from “upstream” - there you typically only have read access.

Hi,

In the projects I’ve contributed to (usually from the GNOME community), usually the master branch points to the latest stuff that is going to be included in the next version. Then there are tags that point to the release commits of master and new development is done in different branches, usually one branch per feature. These feature branches are merge into the master branch when the feature is considered to be done (developed, tested, etc…) and pull requests would be done for this branch as well.

I’m not trying to convince you of a workflow that I’m used to but I wonder why you’re keeping the master branch untouched and using the develop one for the latest stuff.

Out of curiosity, could you please tell me why you have chosen this workflow and if you’ve considered the one I mentioned above?

Thank you,

we used master as the latest during the development of 007 and it was a little messy cause we cannot maintain everything stable at every time. mostly windows since non of the core developers work on a daily basis with it.

So now master has only bugfixes, that way master is always stable + bugfixes and develop has the newest features

Well, I still think you could accomplish this by making sure every feature branch was stable before merging them into master.
But anyway, like I said this was just a suggestion.

However, I have another thing I noticed that I really think we should correct. Git’s “Merged Branch” commits.
These are the automatic commits Git does when one merges/pulls a branch that wasn’t rebased. This makes the git tree cluttered with such commits instead of showing a clean and more readable history.

This can be avoided by rebasing the branches one is about to merge with the target branch. For example, I can have “master” with the latest stuff and a “feature_a” branch that sprung out of “master”. I’ve done stuff on my “feature_a” but meanwhile “master” changed.
For the case above, *before* I merge “feature_a” with “master” I should do (when on “feature_a”): git rebase master
For the pulls, I can do “git rebase master” after the pull or I can do a “git pull --rebase”.

There are ways to automate this a bit as stated in:
http://www.viget.com/extend/only-you-can-prevent-git-merge-commits/

So please take this not as free criticizing but as an improvement for us to have a cleaner and more professional looking git history.

Cheers,

Hey, yeah, no problem, always good to know new things : )

The main problem is there’s lot’s of people contributing to OF and most of them just know how to use git in a basic manner. Also github offers the possibility to merge things from the web interface which is way easier than doing it from the command line so most of the times we just do that.

About master as latest, the main problem is keeping the projects compiling so if someone adds a feature even if that feature is stable it’s probably going to break windows projects and we usually fix windows by the end of the release cycle cause almost no one uses it in a daily basis.

The main problem is there’s lot’s of people contributing to OF and most of them just know how to use git in a basic manner. Also github offers the possibility to merge things from the web interface which is way easier than doing it from the command line so most of the times we just do that.

Hmm, I don’t know GitHub in detail (I use Gitorious: http://gitorious.org/~jrocha ) but maybe there’s a way to rebase the branches after a pull. Otherwise I’d suggest we update branches from the command line because I think having a clean git tree compensates.

About master as latest, the main problem is keeping the projects compiling so if someone adds a feature even if that feature is stable it’s probably going to break windows projects and we usually fix windows by the end of the release cycle cause almost no one uses it in a daily basis.

Yeah, but by stable I also mentioned that we could have it in their own branch until Windows is tested as well.
Also, this would make it much cleaner by being able to apply the Windows’ final fixes to each feature directly in the same commit instead of doing it in a tree with other developments going on (the whole branch “develop”).

Again, I don’t mean to criticize you guys but I really believe that with this bit of workflow changes and discipline we could reach a much more organized code base.

If you’re consider doing it and have some doubts, please let me know.

Cheers,

well, I have to disagree. For one, I find the tree does not look unorganized by using merge commit messages. On the contrary, by using -no-ff (which github uses when you merge pull requests), the merge is recorded in the commit message, and the branch history is preserved in the network view - it is clear how the changes happened, and what happened in which branch, the branches are preserved in the history, and are not fused into the master.
https://github.com/openframeworks/openFrameworks/network
btw, this also seems to be reflected in the comments to the blog post you linked to, lots of people give reasons why not to rebase.

Another advantage of merge commits is that, in case of pull requests, it automatically records the ID of the merged pull request in question into the message, so it makes any follow-up review much easier by directly linking to the merge discussion and diffs etc.

Also, I think having a simple git workflow understandable by as many people as possible definitely trumps commit log cosmetic considerations - I concur with arturo that we can be happy if people understand simple git.

If you’ve read this thread, you’ve probably also read the wiki article on top, and the article that one links to which explains where this workflow is coming from: http://nvie.com/posts/a-successful-git-branching-model/
We already simplified this workflow to adapt it to our situation, so I don’t think we should make it more complicated _again_ with a specialized rebase procedure.
I grant you, though, that merge commits can appear displeasing, but I think that’s largely in the eye of the beholder. This also applies to the different version control workflow models floating around everywhere - there’s always another one which has some (dis)advantages - there’s also people who dislike git-flow (the model in the article I linked to).

Hi bilderbuchi,

I see your point but the thing is that any changes that you pull should work on top of the base branch (usually master but in OF’s case develop) and assuming you don’t pull from different “non-main” branches it is easy to check the difference in order to review the commits pulled: git log my_base_branch…

Of course that if you have several tiny commits to implement a single feature, they will be loose (though on top of each other) in the tree but non-divisible features should come in one commit.

Anyway, like I said, these are just different approaches and that is easier for git beginners to assimilate the current workflow.
Summarizing, I understand and respect the way OF currently works so take these simply as a suggestion and a different point of view.

I hope I can contribute to OF in the future, regardless of the git’s policies :slight_smile:

Cheers,

Yeah, a slightly different workflow shouldn’t bar you from contributing - welcome!
So far I’m glad that we even have a formalized git workflow - we only started this with 007 release, a couple months back, before that it was…not pretty…
So I suggest everybody going along with it for a while. Later when people are more used to it, we can always investigate if there are friction points, and adjust our policies accordingly, but I wouldn’t want to do the whole thing over again now, when everything’s fresh for quite many people…

Thanks. I’m willing to do so.

So far I’m glad that we even have a formalized git workflow - we only started this with 007 release, a couple months back, before that it was…not pretty…
So I suggest everybody going along with it for a while. Later when people are more used to it, we can always investigate if there are friction points, and adjust our policies accordingly, but I wouldn’t want to do the whole thing over again now, when everything’s fresh for quite many people…

Fair enough. I still think that the workflow I’ve suggested is better organized (that’s why many large projects use it) and would make things look clean but I can use the current one and try convincing you all again in the future :slight_smile:

Cheers,