Skip to content

Commit 257b526

Browse files
cloudops-wstevenssebgoa
cloudops-wstevens
authored and
sebgoa
committed
Added instructions for how to contribute: This closes apache#3
Signed-off-by: Sebastien Goasguen <runseb@gmail.com>
1 parent 5c4cc32 commit 257b526

3 files changed

Lines changed: 146 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.rst‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information#
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
Unless required by applicable law or agreed to in writing,
10+
software distributed under the License is distributed on an
11+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
12+
KIND, either express or implied. See the License for the
13+
specific language governing permissions and limitations
14+
under the License.
15+
16+
17+
Apache CloudStack
18+
=================
19+
20+
Apache CloudStack is an Apache project, see <http://cloudstack.apache.org> for
21+
more information.
22+
23+
24+
Website
25+
=======
26+
27+
These docs are on-line at <http://docs.cloudstack.apache.org/en/latest/>
28+
29+
30+
More Info
31+
=========
32+
33+
Refer to the README.rst in the `rtd` directory for more details on how to build the documentation.
34+
35+
36+
Contributing to the documentation
37+
=================================
38+
39+
Initial setup of your fork
40+
--------------------------
41+
42+
In your browser, navigate to: https://github.com/apache/cloudstack-docs
43+
44+
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.
45+
46+
On your computer, follow these steps to setup a local repository for working on the documentation:
47+
48+
.. code:: bash
49+
50+
$ git clone https://github.com/YOUR_ACCOUNT/cloudstack-docs.git
51+
$ cd cloudstack-docs
52+
$ git remote add upstream https://github.com/apache/cloudstack-docs.git
53+
$ git checkout master
54+
$ git fetch upstream
55+
$ git merge upstream/master
56+
57+
58+
Making changes
59+
--------------
60+
61+
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.
62+
63+
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.
64+
65+
.. code:: bash
66+
67+
$ git checkout -b dev
68+
(make your changes)
69+
$ git add .
70+
$ git commit -a -m "commit message for your changes"
71+
72+
.. note::
73+
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`.
74+
75+
76+
Merging `upstream/master` into your `dev` branch
77+
------------------------------------------------
78+
79+
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.
80+
81+
This process will do the following:
82+
83+
#. Checkout your local `master` branch
84+
85+
#. Synchronize your local `master` branch with the `upstream/master` so you have all the latest changes from the official docs
86+
87+
#. Merge the latest changes from the official docs into your `dev` branch so it is up-to-date with the latest changes
88+
89+
.. code:: bash
90+
91+
$ git checkout master
92+
$ git fetch upstream
93+
$ git merge upstream/master
94+
$ git checkout dev
95+
$ git pull . master
96+
97+
.. note:: Now your `dev` branch is up-to-date with all the recent changes in the `upstream/master`.
98+
99+
100+
Making a pull request on GitHub to contribute your changes
101+
----------------------------------------------------------
102+
103+
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.
104+
105+
.. note:: Make sure you have merged `upstream/master` into your `dev` branch before you do this.
106+
107+
.. code:: bash
108+
109+
$ git push origin master
110+
$ git push origin dev
111+
112+
Now that the `dev` branch has been pushed to your GitHub repository, you can initiate the pull request.
113+
114+
To initiate the pull request, do the following:
115+
116+
#. Navigate your browser to your forked repository: https://github.com/YOUR_ACCOUNT/cloudstack-docs
117+
118+
#. Click the new button called 'Compare & pull request' that showed up just above the main area in your forked repository
119+
120+
#. Enter a good description of the work you have done and then click 'Send pull request'
121+
122+
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.
123+
124+
125+
Cleaning up after a successful pull request
126+
-------------------------------------------
127+
128+
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.
129+
130+
.. note:: Make sure that your changes are in `upstream/master` before you delete your `dev` and `origin/dev` branches!
131+
132+
You can delete these deprecated branches with the following:
133+
134+
.. code:: bash
135+
136+
$ git checkout master
137+
$ git branch -D dev
138+
$ git push origin :dev

‎rtd/README.rst‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,20 @@
1313
specific language governing permissions and limitations
1414
under the License.
1515
16+
1617
Apache CloudStack
1718
=================
1819

1920
Apache CloudStack is an Apache project, see <http://cloudstack.apache.org> for
2021
more information.
2122

23+
2224
Website
23-
=============
25+
=======
2426

2527
These docs are on-line at <http://docs.cloudstack.apache.org/en/latest/>
2628

29+
2730
Translation
2831
===========
2932

@@ -58,18 +61,15 @@ Build the translated docs:
5861
sphinx-intl build --locale-dir source/locale
5962
make -e SPHINXOPTS="-D language='ja'" html
6063

64+
6165
Feedback
6266
========
6367

6468
Please send feedback to the mailing list at <dev@cloudstack.apache.org>,
6569
or the JIRA at <https://issues.apache.org/jira/browse/CLOUDSTACK>.
6670

67-
Contributing
68-
============
69-
70-
You can submit a pull request via github or submit patches via review board <https://reviews.apache.org>
71-
72-
For information on how to contribute, please see the Contributing
73-
chapter in our documentation <http://cloudstack.apache.org/developers.html>
7471

72+
Contributing to the documentation
73+
=================================
7574

75+
Refer to the README.rst file in the root directory of this project for instructions on how to contribute to this documentation.

0 commit comments

Comments
 (0)