On May 26, 2014, at 6:08 PM, Will Stevens <williamstev...@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 <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.com>wrote: > > > >> I'm not a fan of squashed merges myself, because you lose the history, > >> which can often contain useful check-in comments. > >> > >> My preferred github workflow is to make a new local branch before > >> starting any change, push that to a branch in my fork of the project > >> on github, and then send a pull request. I don't do subsequent work on > >> the same branch (unless the maintainer wants further changes before > >> accepting the pull request), so I don't run into the problem where > >> pull requests build on each other. > >> > >> Having said that, I'm talking about code, not documentation. There may > >> be some reason I'm not aware of why documentation works better with a > >> different workflow. > >> > >> -- > >> Stephen Turner > >> > >> > >> -----Original Message----- > >> From: williamstev...@gmail.com [mailto:williamstev...@gmail.com] On > >> Behalf Of Will Stevens > >> Sent: 22 May 2014 21:36 > >> To: dev@cloudstack.apache.org; Sebastien Goasguen; Pierre-Luc Dion > >> Subject: [DOCS] Git Flow > >> > >> Hey All, > >> In the the README.rst files in the documentation, it refers to this > >> page if you want to contribute: > >> http://cloudstack.apache.org/developers.html > >> > >> I am not sure those instructions are actually up-to-date or valid for > >> contributing to the documentation. > >> > >> I originally tried to use this process ( > >> https://help.github.com/articles/syncing-a-fork) to keep my > >> documentation fork up-to-date with the upstream/master, but after the > >> first pull request the commits have to be cherry-picked because the > >> pull requests will always take everything I have committed in my fork > >> rather than the changes since the last pull request. This got annoying > >> quickly. > >> > >> When contributing to the actual CloudStack code I used a squashed > >> patch approach which worked very well. I have written up that flow as > >> well as a similar flow for working with Github pull requests. > >> > >> I would like you to review what I have written. If you guys approve > >> of the flow, I would like to add it to the README.rst files in the > >> different documentation repositories to make it easier for people to > >> contribute to the documentation. I know I found it really hard to > >> figure out how to contribute to the documentation initially. We want > >> to lower the bar a bit on this so more people feel comfortable helping > >> with the documentation. > >> > >> L >
