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 <run...@gmail.com> wrote: > > 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 > > > >
