Hi, Good effort. Will you should also see this and update the wiki as needed: https://cwiki.apache.org/confluence/display/CLOUDSTACK/Git
I would say, squashed merges are much better when you're going through list of changes [1] instead of having a branch based workflow, reverting/fixing/bisecting it becomes much easier. I would recommend Stephen and others to checkout Phabricator's pre and post code reviewing and their CLI tool arcanist which IMO give a much better workflow. Right now it's too much pain for a contributor to create a patch, upload to reviewboard, get it reviewed and then for the committer to go see RB, test/review patch and merge it. This is all manual work. Pull request is one good way to solve it at the cost of complicating git trees/graphs, emailing patch directly to ML can be another (historically worked?) and using something like Phabricator (that can be hosted on ASF infra) is another way as well. [1] See the git network/graph: git log --graph --decorate --pretty=oneline --abbrev-commit --all Regards. On Fri, May 23, 2014 at 3:20 PM, Stephen Turner <stephen.tur...@citrix.com>wrote: > 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 >
