How to properly use git to implement a feature

Development matplotlib-devel
#1

I was wanting to add a feature to matplotlib…one that I would use in my application. I also want to contribute the feature back. I’m personally using version 1.1.1 of matplotlib. Disclaimer…I only know enough about git to be dangerous.

So is it best to branch from v1.1.1, implement the feature, and then try to rebase to master? Or is it best to branch from master, implement the feature, and then (somehow) backport the patch to the v1.1.1 tagged version?

Whatever the best choice is, what would the procedure look like to accomplish this?

···

–

Daniel Hyams
dhyams@…149…

#2

If something is a bugfix, I generally branch from v1.1.x (i.e. the
maintenance branch), implement the feature, submit a pull request
for that, which eventually gets merged into the maintenance branch.
Then I merge the maintenance branch into master. The last step can
generally only be done by people with write permissions to the core
repository. I know other projects that work the other way around,
but that’s the way things have generally been done in matplotlib.
git checkout -b my_new_feature upstream/v1.1.x
… implement feature …
git add …files…
git commit
git push origin my_new_feature
…create a pull request on github…
…after the pull request is merged, v1.1.x gets merged into
master…
Mike

···

On 08/12/2012 09:34 PM, Daniel Hyams
wrote:

      I

was wanting to add a feature to matplotlib…one that I would
use in my application. I also want to contribute the feature
back. I’m personally using version 1.1.1 of matplotlib.
Disclaimer…I only know enough about git to be dangerous.

      So

is it best to branch from v1.1.1, implement the feature, and
then try to rebase to master? Or is it best to branch from
master, implement the feature, and then (somehow) backport the
patch to the v1.1.1 tagged version?

      Whatever

the best choice is, what would the procedure look like to
accomplish this?

–

  Daniel Hyams

  dhyams@...149...

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats.

_______________________________________________
Matplotlib-devel mailing list

http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/Matplotlib-devel@lists.sourceforge.nethttps://lists.sourceforge.net/lists/listinfo/matplotlib-devel

#3

I was wanting to add a feature to matplotlib...one that I would use in
my application. I also want to contribute the feature back. I'm
personally using version 1.1.1 of matplotlib. Disclaimer...I only know
enough about git to be dangerous.

So is it best to branch from v1.1.1, implement the feature, and then try
to rebase to master? Or is it best to branch from master, implement the
feature, and then (somehow) backport the patch to the v1.1.1 tagged version?

Mike answered for the case where you are making a bugfix that really does go in v1.1.x. I think that even there, what he is recommending is a bit different from what you have in mind: he is saying to branch from an up-to-date v1.1.x, not from v1.1.1. Similarly, for the case you have in mind, the pull request should be for a change relative to a recent enough point on the master branch that it can be merged cleanly, and with no unexpected side-effects.

It sounds like what you are trying to do is maintain your own branch off of the v1.1.1 tagged version, with only your own features added.

I don't think there is any single best way to do this; it depends on how you work, and on what sorts of changes you are making.

Developing your change in your feature branch off of v1.1.1 is perfectly reasonable, since that is where you are normally working, and that is where you need it to work. To propagate it upstream, you do need to either cherry-pick it, or reimplement it, relative to recent master. Re-implementing it can be simpler in some cases--easier to see what is going on!

I had been thinking "rebase", but this is not correct; you don't want to *remove* your commits from your branch off of v1.1.1, you want to *reproduce* them, or their net effect, in a *new* topic branch off of up-to-date master.

It would go something like this. Assume "upstream" is the remote pointing to the main mpl repo, and "origin" is your github repo. Assume your changes are in a topic branch called "dh_topic_stable", off of v1.1.1. Find the commit numbers in dh_topic_stable that you need to propagate, say "a0b123fed" and "df237abc".

git fetch upstream
git checkout -b dh_topic upstream/master
git cherry-pick a0b123fed df237abc
# build and test; maybe add documentation and test commits
git push origin dh_topic

Then make your pull request against mpl master.

For seeing what is in a repo, and what happens at each step of the way, I find qgit helpful. Invoke as "qgit --all". You need to hit the refresh button after each command-line git call.

Eric

···

On 2012/08/12 3:34 PM, Daniel Hyams wrote:

Whatever the best choice is, what would the procedure look like to
accomplish this?

–
Daniel Hyams
dhyams@…149… <mailto:dhyams@…149…>

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

#4

Thanks Eric; this is what I was looking for, and it’s a shame that there seems to be no way to accomplish this without cherrypicking a commit or range of commits. It seems that since v1.1.1 and master can be traced back to some common ancestry, that git should be able to rewind and replay the changes so that cherrypicking or reimplementing wouldn’t be necessary. I’ve archived this email, though, so that I can use it at the appropriate time.

For the immediate need, I was going to add the keyword ‘bbox_size’ to Annotations, so that the user can optionally specify the box size around an annotation…also was going to add additional boxstyles for Annotations, so that one could use a circle, ellipse, or any other type of patch to enclose the annotation. This would be useful for flowcharting and any other use where the user wants a “patch with text inside”.

As it stands, though I can only get 95% of this done…I can’t seem to get the placement of the patch correct when the text is rotated, unless ha=‘center’ and va=‘center’, or if rotation_mode=‘anchor’. So since I would cause a regression here, I guess it’s off the table.

···

On Sun, Aug 12, 2012 at 11:23 PM, Eric Firing <efiring@…229…> wrote:

On 2012/08/12 3:34 PM, Daniel Hyams wrote:

I was wanting to add a feature to matplotlib…one that I would use in

my application. I also want to contribute the feature back. I’m

personally using version 1.1.1 of matplotlib. Disclaimer…I only know

enough about git to be dangerous.

So is it best to branch from v1.1.1, implement the feature, and then try

to rebase to master? Or is it best to branch from master, implement the

feature, and then (somehow) backport the patch to the v1.1.1 tagged version?

Mike answered for the case where you are making a bugfix that really

does go in v1.1.x. I think that even there, what he is recommending is

a bit different from what you have in mind: he is saying to branch from

an up-to-date v1.1.x, not from v1.1.1. Similarly, for the case you have

in mind, the pull request should be for a change relative to a recent

enough point on the master branch that it can be merged cleanly, and

with no unexpected side-effects.

It sounds like what you are trying to do is maintain your own branch off

of the v1.1.1 tagged version, with only your own features added.

I don’t think there is any single best way to do this; it depends on how

you work, and on what sorts of changes you are making.

Developing your change in your feature branch off of v1.1.1 is perfectly

reasonable, since that is where you are normally working, and that is

where you need it to work. To propagate it upstream, you do need to

either cherry-pick it, or reimplement it, relative to recent master.

Re-implementing it can be simpler in some cases–easier to see what is

going on!

I had been thinking “rebase”, but this is not correct; you don’t want to

remove your commits from your branch off of v1.1.1, you want to

reproduce them, or their net effect, in a new topic branch off of

up-to-date master.

It would go something like this. Assume “upstream” is the remote

pointing to the main mpl repo, and “origin” is your github repo. Assume

your changes are in a topic branch called “dh_topic_stable”, off of

v1.1.1. Find the commit numbers in dh_topic_stable that you need to

propagate, say “a0b123fed” and “df237abc”.

git fetch upstream

git checkout -b dh_topic upstream/master

git cherry-pick a0b123fed df237abc

build and test; maybe add documentation and test commits

git push origin dh_topic

Then make your pull request against mpl master.

For seeing what is in a repo, and what happens at each step of the way,

I find qgit helpful. Invoke as “qgit --all”. You need to hit the

refresh button after each command-line git call.

Eric

Whatever the best choice is, what would the procedure look like to

accomplish this?

–

Daniel Hyams

dhyams@…149… mailto:dhyams@...149...

Live Security Virtual Conference

Exclusive live event will cover all the ways today’s security and

threat landscape has changed and how IT managers can respond. Discussions

will include endpoint security, mobile security and the latest in malware

threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/

Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Live Security Virtual Conference

Exclusive live event will cover all the ways today’s security and

threat landscape has changed and how IT managers can respond. Discussions

will include endpoint security, mobile security and the latest in malware

threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/

Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

–
Daniel Hyams
dhyams@…149…