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
