cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen Turner <Stephen.Tur...@citrix.com>
Subject RE: [DOCS] Git Flow
Date Fri, 23 May 2014 09:50:34 GMT
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: williamstevens@gmail.com [mailto:williamstevens@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
Mime
View raw message