Re: [DOCS] Git Flow
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 williamstev...@gmail.comwrote: 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 stephen.tur...@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: rohityada...@gmail.com [mailto:rohityada...@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 stephen.tur...@citrix.comwrote: 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
Re: [DOCS] Git Flow
.. 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 williamstev...@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 stephen.tur...@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: rohityada...@gmail.com [mailto:rohityada...@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 stephen.tur...@citrix.comwrote: 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
Re: [DOCS] Git Flow
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 williamstev...@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 stephen.tur...@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: rohityada...@gmail.com [mailto:rohityada...@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 stephen.tur...@citrix.comwrote: 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
Re: [DOCS] Git Flow
On May 22, 2014, at 10:35 PM, Will Stevens wstev...@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
RE: [DOCS] Git Flow
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`
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 stephen.tur...@citrix.comwrote: 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
RE: [DOCS] Git Flow
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: rohityada...@gmail.com [mailto:rohityada...@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 stephen.tur...@citrix.comwrote: 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
Re: [DOCS] Git Flow
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 stephen.tur...@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: rohityada...@gmail.com [mailto:rohityada...@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 stephen.tur...@citrix.comwrote: 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. L
