I'm not a fan of squashed merges myself, because you lose the history, which can often contain useful check-in comments.
My preferred github workflow is to make a new local branch before starting any change, push that to a branch in my fork of the project on github, and then send a pull request. I don't do subsequent work on the same branch (unless the maintainer wants further changes before accepting the pull request), so I don't run into the problem where pull requests build on each other. Having said that, I'm talking about code, not documentation. There may be some reason I'm not aware of why documentation works better with a different workflow. -- Stephen Turner -----Original Message----- From: williamstev...@gmail.com [mailto:williamstev...@gmail.com] On Behalf Of Will Stevens Sent: 22 May 2014 21:36 To: dev@cloudstack.apache.org; Sebastien Goasguen; Pierre-Luc Dion Subject: [DOCS] Git Flow Hey All, In the the README.rst files in the documentation, it refers to this page if you want to contribute: http://cloudstack.apache.org/developers.html I am not sure those instructions are actually up-to-date or valid for contributing to the documentation. I originally tried to use this process ( https://help.github.com/articles/syncing-a-fork) to keep my documentation fork up-to-date with the upstream/master, but after the first pull request the commits have to be cherry-picked because the pull requests will always take everything I have committed in my fork rather than the changes since the last pull request. This got annoying quickly. When contributing to the actual CloudStack code I used a squashed patch approach which worked very well. I have written up that flow as well as a similar flow for working with Github pull requests. I would like you to review what I have written. If you guys approve of the flow, I would like to add it to the README.rst files in the different documentation repositories to make it easier for people to contribute to the documentation. I know I found it really hard to figure out how to contribute to the documentation initially. We want to lower the bar a bit on this so more people feel comfortable helping with the documentation. Let me know what you think. Cheers, Will ---- Contributing to the documentation ================================= Initial setup of your local fork -------------------------------- First, fork the original documentation repository to your Github account. Then on your computer, do the following... .. code:: bash $ git clone `url of your forked repo` $ cd `git repo directory` $ git remote add upstream `url of the original repo` $ git checkout master $ git fetch upstream $ git merge upstream/master Making changes -------------- You will be making changes on a new `dev` branch which is only in your local git repository. .. code:: bash $ git checkout -b dev (make your changes) $ git add . $ git commit -a -m "commit message for your changes" .. note:: The `-b` specifies that you want to create a new branch called `dev`. You only specify `-b` the first time because you are creating a new branch. Once the `dev` branch exists, you can later switch to it with `git checkout dev`. Merging `upstream/master` into your `dev` branch ------------------------------------------------ .. code:: bash $ git checkout master $ git fetch upstream $ git merge upstream/master $ git checkout dev $ git pull . master .. note:: Now your `dev` branch is up-to-date with everything from `upstream/master`. Making a squashed patch for `upstream/master` --------------------------------------------- .. note:: Make sure you have merged `upstream/master` into your `dev` branch before you do this. .. code:: bash $ git checkout master $ git checkout -b squashed $ git merge --squash dev $ git commit -a -m "commit message for this squashed patch" $ git format-patch master $ git checkout master $ git branch -D squashed Upload the resulting patch file to a committer and move it out of your working tree. Continue working on the `dev` branch. When your changes are committed to the `upstream/master`, they will end up in your `master` branch when you re-sync your local `master` with the `upstream/master`. The next time you create a squashed patch between the `dev` branch and `master`, it will only include the changes that are not already in the `upstream/master` branch. Making a squashed pull request for `upstream/master` ---------------------------------------------------- .. note:: Make sure you have merged `upstream/master` into your `dev` branch before you do this. .. code:: bash $ git checkout master $ git checkout -b squashed $ git merge --squash dev $ git commit -a -m "commit message for this squashed pull request" $ git push origin master $ git push origin squashed Create a pull request on the `squashed` branch in your forked git repo on github to contribute it back to `upstream/master`. Continue working on the `dev` branch. When your changes are committed to the `upstream/master`, they will end up in your `master` branch when you re-sync your local `master` with the `upstream/master`. The next time you create a squashed pull request between the `dev` branch and `master`, it will only include the changes that are not already in the `upstream/master` branch. Once the `squashed` branch is committed into the `upstream/master` branch, your local `squashed` branch and the `origin/squashed` branch are not needed anymore (until you want to do the process again). You can delete them with the following... .. code:: bash $ git checkout master $ git branch -D squashed $ git push origin :squashed
