Contributing to a repository on GitHub on a new branch

Question

Say someone owns a repository with only one master hosting code that is compatible with Python 2.7.X . I would like to contribute to that repository with my own changes to a new branch new_branch to offer a variant of the repository that is compatible with Python 3 .

I followed the steps here :

1. I forked the repository on GitHub on my account
2. I cloned my fork on my local machine
3. I created a new branch new_branch locally
4. I made the relevant changes
5. I committed and pushed the changes to my own fork on GitHub
6. I went on the browser to the GitHub page of the official repository, and asked for a pull request

The above worked, but it did a pull request from "my_account:new_branch" to "official_account:master" . This is not what I want, since Python 2.7.x and Python 3 are incompatible with each other. What I would like to do is create a PR to a new branch on the official repository (eg with the same name "new_branch" ). How can I do that? Is this possible at all?

Answer 1

You really don't want to do things this way. But first I'll explain how to do it, then I'll come back to explain why not to.

Using Pull Requests at GitHub has a pretty good overview, in particular the section "Changing the branch range and destination repository." It's easiest if you use a topic branch, and have the upstream owner create a topic branch of the same name; then you just pull down the menu where it says "base: master" and the choice will be right there, and he can just click the "merge" button and have no surprises.

So, why don't you want to do things this way?

First, it doesn't fit the GitHub model. Topic branches that live forever in parallel with the master branch and have multiple forks make things harder to maintain and visualize.

Second, you need both a git URL and an https URL for you code. You need people to be able to share links, pip install from top of tree, just clone the repo instead of cloning and then checking out a different branch, etc. This all means your code has to be on the master branch.

Third, if you want people to be able to install your 3.x version off PyPI, find docs at readthedocs, etc., you need a single project with a single source tree. Most such sites have a single latest version, not a latest version for each Python version, and definitely not multiple variations of the same version. (You could install completely fork the project, and create a separate foo3 project. But it's much easier for people to be able to pip install foo than to have them try that, fail, come to SO and ask why it doesn't work, and get told they probably have Python 3 and need to pip install foo3 instead.)

How do you merge two versions into a single package? The porting docs should have the most up-to-date advice, but briefly: If it's at all possible to create a single codebase that runs on both versions, that's ideal; if not, and if you can't make things work by running 2to3 or 3to2 at install time, create a parallel directory for the 3.x code (eg, a foo3 alongside foo ) and pick the appropriate directory at install time. (You can always start with that and gradually work toward a unified codebase.)