Cake How To's

switch_to_feature_branch.md

NOTE: Please read through all of this guide before running through the commands it shows, just to be clear that you understand the entire process

Current situation

You are attempting to make a contribution to the main Cake repository. First of all, thank you very much, we greatly appreciate your contributions! However, the work that you have started is on the develop branch, rather than on a feature branch as suggested in our contributing.md file. Don't worry, we can fix that, but we really would encourage you to read all of the contributing guide, in order to ensure you are following all the suggestions that we have made.

The reason that we ask you to use a feature branch is quite simple. Once you have completed the work that you would like to contribute to Cake, there is an indeteminate period of time before that work will get pulled into Cake. Bottom line, all members of the Cake team are busy, and it can take some time for your work to get looked at, reviewed, and hopefully pulled in. Within this period of time, other work might have been merged into the develop branch, and as a result, your work is "out-of-date". It is a reasonably trivial matter to update your work, assuming you are working on a feature branch. If you aren't on a feature branch, then doing this update becomes a lot harder.

How to solve the problem

First things first...

We want to make sure that we don't lose any of your work. Please make sure that you have committed all the local changes that you have, and that you have pushed all of your commits to your fork of the Cake repository. Once you have done this, take a FULL copy of your local git repository, and put it somewhere else. This is your fall back strategy should things go completely wrong.

Let's get started

Some assumptions...

1. You have a fork of the main Cake repository in your own GitHub account
2. You have this fork cloned locally onto your own machine
3. You have done some work on the develop branch of this repository, and you want to move this work to a feature branch, ready for submitting a Pull Request
4. You have configured an "upstream" remote from your local git repository, back to the main Cake repository on GitHub
5. You can confirm this by running the following command git remote -v. You should see something like the following:
6. In the above, you will see that I have two remotes which point to the same location. This is simply because I always have a remote called upstream pointing at the repository that my fork was cloned from. I find this a good convention, and I would recommend that you do the same. The remainder of this description will assume that you have a remote called upstream.
7. If you don't have this remote, run the following command to add it git remote add upstream https://github.com/cake-build/cake.git
8. Run the git remote -v command to ensure that it was added correctly

Ok, let's get started...

1. Ensure that you are on the develop branch git checkout develop
2. Create a new branch git checkout -b feature/GH-1234 develop NOTE: Here we are creating a branch called feature/GH-1234 and basing it on what is contained within the current develop branch. NOTE: The name feature/GH-1234 is a convention that we use where GH-1234 refers to the GitHub Issue Number that is associated with the current thing that you are working on. As per our contributing guidelines, this issue should exist, and as a result, you should be able to reference it.
3. Switch back to the develop branch git checkout develop
4. Fetch the latest work from upstream git fetch upstream -v
5. Now we need to undo the work that you have done on this branch (don't worry, the work that you have done is over on the feature branch that we just created) git reset --hard upstream/develop
6. Push the resetted version of the develop branch back to your fork git push -f origin develop
7. Now we are ready to update the feature branch with the latest code from develop branch, do the following
8. Switch back to your feature branch git checkout feature/GH-1234
9. Rebase the changes from develop onto your feature branch git rebase develop
10. Hopefully, everything will have worked correctly, and you don't have any merge conflicts. If there are merge conflicts, that is a bigger discussion, and we can come back to that.
11. Assuming everything did work correctly, without errors, you are now in a position to push your changes. Run the command git push You should see something like this
12. Simply do what it says, and run this command: git push --set-upstream origin feature/GH-1234 NOTE: Obvioulsy replace the branch name with what yours is called. This happens due to the fact that there is no branch in your fork with the name of the feature branch that you created locally, and it needs to be told how to hook them up
13. With that done, go to GitHub in the browser, and submit a new PR from the feature branch that you just created in your fork on GitHub and send it to the develop branch on the main Cake repository

If you run into any issues with this guide, then comment on this issue that you have raised, and we can help you look into the problems you are facing.