cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Will Stevens <>
Subject Re: [DOCS] Git Flow
Date Mon, 26 May 2014 16:08:16 GMT
Thank you all for the feedback, that was very helpful.

I have adjusted my steps quite a bit.  Here is an overview...
- I have removed the 'squashed' concept.  I think it makes sense that the
'default' way that people contribute is with a full history of their
changes and commit messages.  I hope this does not increase the amount of
work for the people committing the pull requests, but I have not seen that
process yet.
- I have removed the concept of 'patches' from this flow.  I originally
wrote this for patching because this is how I commit to code, but this flow
is different and we should not confuse the two when documenting how to
contribute to the documentation.
- I have done a much better job of describing why we do the different steps
and why the different pieces are important.  You guys made good comments on
those aspects, so I tried to incorporate your feedback.
- Instead of making a generic guide, I customized this guide to the
specific documentation repository.  I will do an initial pull request for
this addition to the README.rst file for the 'cloudstack-docs-admin'
repository.  If everyone is happy with this, I will create the equivalent
customized additions for the other README.rst files and create pull request
for them.  I did this because not seeing a real URL may confuse new people
when trying to do these steps.  Since this will be shown on the front page
of the GitHub repo, it makes sense that it is setup for that repo.

I think that is pretty much it.  I will create a pull request for the
'cloudstack-docs-admin' repo now with what is below.  If you have comments
or suggestions, please let me know and I will update the doc.




Contributing to the documentation

Initial setup of your fork

In your browser, navigate to:

Fork this repository by clicking on the 'Fork' button on the top right hand
side.  The fork will happen and you will be taken to your own fork of the
repository.  On the right hand side of the page of your fork, under 'HTTPS
clone URL', copy the URL to your clipboard by clicking the the clipboard
just right of the URL.

On your computer, follow these steps to setup a local repository for
working on the documentation:

.. code:: bash

$ git clone
$ cd cloudstack-docs-admin
$ git remote add upstream
$ git checkout master
$ git fetch upstream
$ git merge upstream/master

Making changes

It is important that you create a new branch to make changes on and that
you do not change the `master` branch (other than to pull in changes from
`upstream/master`).  In this case I will assume you will be creating a
branch called `dev` to make your changes in.  This `dev` branch will be
created on your local repository and will then be pushed to your forked
repository on GitHub where you will create a Pull Request for the changes
to be committed into the official documentation.

It is good practice to create a new branch each time you want to contribute
to the documentation and only track the changes for that pull request in
this branch.

.. 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 only `git
checkout dev`.

Merging `upstream/master` into your `dev` branch

It is important that you maintain an up-to-date `master` branch in your
local repository.  This is done by merging in the `upstream/master` (the
official documentation repository) into your local repository.  You will
want to do this before you start working on a feature as well as right
before you submit your changes as a pull request.  You can also do this
process periodically while you work on your changes to make sure you are
working off the most recent version of the documentation.

This process will do the following:

#. Checkout your local `master` branch

#. Synchronize your local `master` branch with the `upstream/master` so you
have all the latest changes from the official docs

#. Merge the latest changes from the official docs into your `dev` branch
so it is up-to-date with the latest changes

.. 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 all the recent changes
in the `upstream/master`.

Making a pull request on GitHub to contribute your changes

When you are happy with your changes and you want to contribute them, you
will be creating a Pull Request on GitHub to do so.  This is done by
pushing your changes to your forked repository (usually called 'origin')
and then initiating a pull request.

.. note:: Make sure you have merged `upstream/master` into your `dev`
branch before you do this.

.. code:: bash

$ git push origin master
$ git push origin dev

Now that the `dev` branch has been pushed to your GitHub repository, you
can initiate the pull request.

To initiate the pull request, do the following:

#. Navigate your browser to your forked repository:

#. Click the new button called 'Compare & pull request' that showed up just
above the main area in your forked repository

#. Enter a good description of the work you have done and then click 'Send
pull request'

If you are requested to make modifications to your proposed changes, make
the changes locally on your `dev` branch, re-push the changes and submit
the pull request again.

Cleaning up after a successful pull request

Once the `dev` branch has been committed into the `upstream/master` branch,
your local `dev` branch and the `origin/dev` branch are not needed anymore.
 If you want to make additional documentation changes, restart the process
with a new branch.

.. note:: Make sure that your changes are in `upstream/master` before you
delete your `dev` and `origin/dev` branches!

You can delete these deprecated branches with the following:

.. code:: bash

$ git checkout master
$ git branch -D dev
$ git push origin :dev

On Fri, May 23, 2014 at 9:01 AM, Will Stevens <>wrote:

> All good feedback. Thanks.
> I will rework this on Monday and add a PR for adding it to the readmes.
> Thx,
> Will
> On Friday, May 23, 2014, Stephen Turner <> wrote:
> > I've not seen Phabricator, but yes, what I like about github is that the
> code review is built into the source control. This makes the whole workflow
> much simpler.
> >
> > --
> > Stephen Turner
> >
> >
> > -----Original Message-----
> > From: [] On Behalf
> Of Rohit Yadav
> > Sent: 23 May 2014 11:35
> > To:
> > Cc: Sebastien Goasguen; Pierre-Luc Dion
> > Subject: Re: [DOCS] Git Flow
> >
> > Hi,
> >
> > Good effort. Will you should also see this and update the wiki as needed:
> >
> >
> > 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
> > <>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: [] On
> >> Behalf Of Will Stevens
> >> Sent: 22 May 2014 21:36
> >> To:; 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:
> >>
> >>
> >> 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 (
> >> 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.
> >>
> >> L

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message