Is this best practice, or should I make a local v1.0.x first and then create the feature branch off of that?

I don't see any real reason to create an intermediate local branch.

Either one should be fine. Personally, I have a local v1.0.x branch that I set up to track matplotlib/v1.0.x, not darrendale/v1.0.x. I don't want to worry about keeping my remote darrendale/v1.0.x branch in sync with matplotlib/v1.0.x.

I think the best practice can be stated thus: if the remote has a branch v1.0.x and you make a local copy of it, the state of your local copy should not diverge from the remote. Use "git pull" occasionally to keep it in sync with the remote, and especially when you are about to do a merge. The only time the state of your local copy should diverge from the remote is right before a push, when you do the merge. Right after the push, your local copy and the remote are once again in sync.

By the way, this:

git branch my-new-feature remotes/origin/v1.0.x
git checkout my-new-feature

is equivalent to:

git checkout -b my-new-feature remotes/origin/v1.0.x

and it also appears to be equal to:

git checkout -b my-new-feature origin/v1.0.x

One final comment: I find the "origin" and "upstream" convention to be confusing. Instead, I name my remotes after the github profiles: "matplotlib" instead of "upstream", "darrendale" instead of origin. Its a little more concrete.

After reading Jouni's comment and rereading my own, I think I agree that it is easier to not have an intermediate, local v1.0.x branch.

I think changing the two commands to "git checkout -b my-new-feature origin/v1.0.x" makes sense.

I'm really not sure if this is correct. The manpage seems to suggest this, but it's really not clear. Can someone else clarify what this does?

I think this is correct. It makes the local branch "track" the remote branch, and while the documentation mainly talks about fetching or pulling getting the remote branch as default, also pushing uses the tracking branch by default.

Yes, I just tested it. Although, "git push" also pushed my v1.0.x and master branches at the same time as my test branch, because I had not been keeping those branches in my personal remote up to date.

Note that you can also view the .git/config file, where your --set-upstream information was stored.

We should avoid words like "with" that don't have a sense of directionality -- it's very ambiguous. Here I've changed it to "into", but I hope I have the direction correct.

Looks right, and I agree that the directional wording is better.

Creating the feature branch based on the maintenance branch like I suggested above does not seem to set the correct base branch when the pull request is made on github.com. Am I doing it wrong?

Doesn't work for me either. I think maybe pull requests always default to master, but I could be wrong.

I noticed the same thing. I do not think you are doing it wrong. It may be a bug at github.

Actually, maybe github doesn't have the information needed to figure this out. Git branches are basically just names for commits, and the fact that my-feature-branch was branched off of origin/v1.0.x isn't recorded anywhere. The history of which commit e.g. the v1.0.x branch used to point to is only recorded in the reflog, which is a very ephemeral thing that gets cleared every now and then.

This is one of the things about git that seem odd at first, but kind of make sense once you understand the idea of branches. I ran into this in another project when I wanted to run git bisect only along the history of master, to find out which feature branch introduced a bug without running tests in intermediate versions on the feature branches. This is basically not doable using the information in the commit graph (except you can make it a rule that feature branches are always merged into master, so master is always the first parent of a merge commit; but you have to enforce the rule, because a merge in the other direction looks the same except for the order of the parents).

Instructions should probably also be added for keeping up to date with the private repository. I think "git pull" is sufficient, but that may not be the case for branches, etc.

If you are branching from your private remote, then yes, pushing your changes is a good idea. Otherwise, it will appear that all of your developments branch off of the same point in history: the day you made your personal fork.

Depends on what "the private repository" means. I guess you mean that you develop on several computers, and want to use github to keep them in sync. Then I think you would want to make your local branches track their respective branches on your github repository, and run "git push" when you are done on one machine, and every time you start working on another machine, check out the relevant branch and run "git pull".

Do note that your github repository is publicly visible, so if you have a workflow where you have private branches that you rebase at will but push to your github repository, it would be a good idea to make it clear which branches are meant for public consumption and which ones not.

I don't think I explained myself clearly. For cross-platform testing, I have clones on about 3 different physical machines, and 8 virtual machines. I'm trying to minimize the amount of work and confusion associated with that. The "git fetch upstream ; git merge upstream/master" commands pull in any recent changes from the central repository into the clone on my local machine. But, if I understand correctly, this does not have any effect on my personal repository, so would need to be performed in every clone. Is that just how it's supposed to work -- this particular merge should never have conflicts, after all, since in the workflow described here, new features are never added to master. Or is it better to do this merge, push it back to my personal repository, and then simply use "git pull" on all my other clones?

Oh, right. For the master branch (and similarly for maintenance branches) this should be a "fast forward" merge, i.e. your branch should be an ancestor of upstream/master and is just updated to point to the same commit. This kind of merge can be done on each repository separately or pushed to your own github repository and pulled from there. I don't see any big advantage either way, but the push/pull workflow seems a little bit more complicated.

For non-fast-forward merges on feature branches, you would most likely obtain a different commit hash on each repository (it depends on the commit message, and I'm not sure if it depends on the date), so then it's important to do the merge once and push/pull it to the other repositories.

Ok. I'll leave the instructions as-is.

To put my question another way: Does performing this merge also pull in changes that may exist only on a maintenance branch? Or is there another step that needs to be performed if I'm, say, working on a bug fix for a maintenance branch, and want to test that it's compatible with any recent changes on that maintenance branch before filing a pull request?

Yes, the maintenance branches are very much like "master" and should be handled in the same way. Whatever you do on "master" has no effect on a maintenance branch and vice versa.

Ok -- so given that above we are recommending not having a separate personal maintenance branch that bugfix branches are built off of, how would one merge upstream changes on a maintenance branch? We are also recommending not merging changes onto feature/bugfix branches, so I'm not sure how it would be done. Apologies if I'm not getting something obvious.

If you do have a local maintenance branch, handle it as you would handle master: don't commit features on it, and keep it up-to-date by pulling into it from the corresponding upstream branch as necessary. If you don't have a local maintenance branch, you can run git fetch upstream to update your local information on the remote branches (so git checkout -b upstream/v1.0.x branches from the current position of v1.0.x).

If you don't have a local maintenance branch but want to merge the current maintenance branch into your feature branch (which shouldn't be necessary, most of the time) run git pull upstream v1.0.x, assuming upstream is the remote corresponding to github.com/matplotlib/matplotlib. If you want to test that your branch merges cleanly, do the merge and then run git reset --hard HEAD^, or use git pull --no-commit upstream v1.0.x and then git reset --hard.

I'm having trouble following this, and maybe I'm asking the wrong questions.

The use case is: I'm working on a bugfix to 1.0.x, so I create a new branch based off of 1.0.x:

git checkout -b bugfix v1.0.x

I work on the bugfix for a while -- it turns out it's non-trivial and I can't finish right away -- days go by -- in the meantime 1.0.x may have changed considerably. I want to confirm that the work I've done on the bugfix is compatible with those changes. So I do "git pull upstream v1.0.x". Why do you say this shouldn't be necessary most of the time? Shouldn't it be something to check as a matter of course before pushing anything? What do the other steps do and why are they necessary? Shouldn't a pull be enough to tell me if my changes merge cleanly?

I think this conversation is a good way of finding out the questions that the documentation needs to answer.

Where I work, we have a workflow where everyone works on a feature branch and when they're done (and all tests pass), submits it to a homebrew review system. Others look at the diff and add their comments. We rotate the task of merging into master: someone periodically merges accepted branches, runs the test suite and if it passes, pushes the master onto the centralized server. Sometimes the review process can take pretty long if the changes are big or if everyone is busy.

In this workflow it is pretty rare to have merge conflicts. People tend to be working on different tasks and so mostly touch different parts of the code, and if they do touch the same code, they tend to talk to each other and figure out how to make their changes work together. Even if you test that the current branch merges cleanly, there is no guarantee of the order in which different branches get merged, so the merge could fail later. We have agreed that the submitter should run the tests before the merge, and whoever merges the branches into master should run the test after the merge. That way we make sure that master is always in good condition, and since the tests pass before the merge, it's not very common for them to fail after the merge. It's also fine for the person doing the merging to fix obvious merge conflicts, since the tests get run after the merge anyway.

So: the extra check before pushing your feature branch doesn't usually catch anything, and it isn't sufficient either, because the branch being merged into can change between when you push and when it gets merged. The important checks are that tests pass before you push and after the merge (so whoever is doing merges should run the tests). Checking that the branch merges doesn't hurt, and doesn't take a lot of time.

A pull is enough to check that the branch would merge. If you push your branch after pulling master (or the maintenance branch) into it, you create extra nodes in the revision history graph, and many people seem to think this is bad. (Personally I don't mind, but this is an opinion held by many people, e.g. Linus.) That's why I recommend that if the merge goes fine, you discard the merge commit and push the branch as it was before the merge.

Finally, if you have developed the branch in private -- you did not push it on github, or at least you did not ask anyone else to build on it -- it's fine to rebase it on top of the branch you want it merged into (e.g. master). Rebasing does not create a merge commit; instead it applies the effect of ever commit on your branch on top of current master, creating a new series of commit objects. That's bad if someone has references to the old commit objects, but it makes the history look cleaner.