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 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 >
