You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Will Stevens <ws...@cloudops.com> on 2014/05/22 22:35:55 UTC
[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
Re: [DOCS] Git Flow
Posted by sebgoa <ru...@gmail.com>.
On May 22, 2014, at 10:35 PM, Will Stevens <ws...@cloudops.com> wrote:
> 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
correct, and yes this page does not explain how to do a pull request
>
> I am not sure those instructions are actually up-to-date or valid for
> contributing to the documentation.
they are if you use review board to upload your patch.
>
> 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.
yes definitely we want the lower bar. I think the bar is very low for folks who want to correct typos and small errors. But if you are doing some significant work you workflow is correct.
I talked with pdion891 on IRC yesterday and basically told him to always keep his master 'clean'. always work in a local topic branch and when the pr is merged pull in the changes in your master, delete the topic branch and create a new one for your new pr.
>
> 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…
>
Maybe add a bit of info about how to fork. you can git clone directly or you can click on the 'edit on github' icon, this will fork automatically but won't be cloned in your local machine.
> .. 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
maybe give the patch a name ? --stdout > mypatch.patch
> $ git checkout master
> $ git branch -D squashed
>
> Upload the resulting patch file to a committer and move it out of your working tree.
>
via review board.
> 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`
> ----------------------------------------------------
specify that it's through github ?
>
> .. 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
>
>
I am not real git expert but I think this workflow works well. Personnally (when I was not a committer on libcloud), I tend to develop in a dev branch and submit pr from there, I don't really squash.
The most important point being to keep your master clean (not local commits in it), keep it in sync when things get merged and don't forget to push it to your remote origin.+1
+1 on putting this in the docs README
>
Re: [DOCS] Git Flow
Posted by Will Stevens <wi...@gmail.com>.
I did not do one for cloudstack-docs yet because it did not have an
existing README file and I am relatively new to this documentation system
and I didn't want to break something by adding a new file.
I don't mind adding a README.rst file assuming it won't cause any problems.
:)
Cheers,
Will
On Mon, May 26, 2014 at 2:07 PM, sebgoa <ru...@gmail.com> wrote:
>
> On May 26, 2014, at 6:08 PM, Will Stevens <wi...@gmail.com>
> wrote:
>
> > 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.
> >
>
> Looks fine to me at a glance.
>
> I committed to all three repos (did not see anything for cloudstack-docs
> itself).
>
> thanks a lot for the patch
>
> -sebastien
>
> > Cheers,
> >
> > Will
> >
> > -----
> >
> > Contributing to the documentation
> > =================================
> >
> > Initial setup of your fork
> > --------------------------
> >
> > In your browser, navigate to:
> https://github.com/apache/cloudstack-docs-admin
> >
> > 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
> https://github.com/YOUR_ACCOUNT/cloudstack-docs-admin.git
> > $ cd cloudstack-docs-admin
> > $ git remote add upstream
> https://github.com/apache/cloudstack-docs-admin
> > $ 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:
> https://github.com/YOUR_ACCOUNT/cloudstack-docs-admin.git
> >
> > #. 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 <wi...@gmail.com>
> 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 <St...@citrix.com>
> 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: rohityadav89@gmail.com [mailto:rohityadav89@gmail.com] On
> Behalf Of Rohit Yadav
> > > Sent: 23 May 2014 11:35
> > > To: dev@cloudstack.apache.org
> > > 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:
> > > 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
> > > <St...@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: 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.
> > >>
> > >> L
> >
>
>
Re: [DOCS] Git Flow
Posted by sebgoa <ru...@gmail.com>.
On May 26, 2014, at 6:08 PM, Will Stevens <wi...@gmail.com> wrote:
> 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.
>
Looks fine to me at a glance.
I committed to all three repos (did not see anything for cloudstack-docs itself).
thanks a lot for the patch
-sebastien
> Cheers,
>
> Will
>
> -----
>
> Contributing to the documentation
> =================================
>
> Initial setup of your fork
> --------------------------
>
> In your browser, navigate to: https://github.com/apache/cloudstack-docs-admin
>
> 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 https://github.com/YOUR_ACCOUNT/cloudstack-docs-admin.git
> $ cd cloudstack-docs-admin
> $ git remote add upstream https://github.com/apache/cloudstack-docs-admin
> $ 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: https://github.com/YOUR_ACCOUNT/cloudstack-docs-admin.git
>
> #. 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 <wi...@gmail.com> 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 <St...@citrix.com> 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: rohityadav89@gmail.com [mailto:rohityadav89@gmail.com] On Behalf Of Rohit Yadav
> > Sent: 23 May 2014 11:35
> > To: dev@cloudstack.apache.org
> > 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:
> > 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
> > <St...@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: 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.
> >>
> >> L
>
Re: [DOCS] Git Flow
Posted by Will Stevens <wi...@gmail.com>.
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.
Cheers,
Will
-----
Contributing to the documentation
=================================
Initial setup of your fork
--------------------------
In your browser, navigate to:
https://github.com/apache/cloudstack-docs-admin
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 https://github.com/YOUR_ACCOUNT/cloudstack-docs-admin.git
$ cd cloudstack-docs-admin
$ git remote add upstream https://github.com/apache/cloudstack-docs-admin
$ 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:
https://github.com/YOUR_ACCOUNT/cloudstack-docs-admin.git
#. 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 <wi...@gmail.com>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 <St...@citrix.com> 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: rohityadav89@gmail.com [mailto:rohityadav89@gmail.com] On Behalf
> Of Rohit Yadav
> > Sent: 23 May 2014 11:35
> > To: dev@cloudstack.apache.org
> > 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:
> > 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
> > <St...@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: 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.
> >>
> >> L
>
Re: [DOCS] Git Flow
Posted by Will Stevens <wi...@gmail.com>.
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 <St...@citrix.com> 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: rohityadav89@gmail.com [mailto:rohityadav89@gmail.com] On Behalf Of
Rohit Yadav
> Sent: 23 May 2014 11:35
> To: dev@cloudstack.apache.org
> 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:
> 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
> <St...@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: 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.
>>
>> L
RE: [DOCS] Git Flow
Posted by Stephen Turner <St...@citrix.com>.
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: rohityadav89@gmail.com [mailto:rohityadav89@gmail.com] On Behalf Of Rohit Yadav
Sent: 23 May 2014 11:35
To: dev@cloudstack.apache.org
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:
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
<St...@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: 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
>
Re: [DOCS] Git Flow
Posted by Rohit Yadav <bh...@apache.org>.
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
<St...@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: 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
>
RE: [DOCS] Git Flow
Posted by Stephen Turner <St...@citrix.com>.
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