72dac7692a9efc9fcccecbe69a96271b8555eb1d
[cordova-docs.git] / README.md
1 Introduction
2 ============
3
4 This repository contains the source code behind [cordova.io](http://cordova.io) and some of its subdomains (namely, [docs.cordova.io](http://docs.cordova.io) and [plugins.cordova.io](http://plugins.cordova.io)).
5
6 Installing
7 ==========
8
9 ## Ruby
10
11 ### Mac OS X
12
13 Install Homebrew from [this site][homebrew], and then run:
14
15     brew install ruby
16
17 ### Windows
18
19 Follow these steps:
20
21 1. Download [this installer][ruby_installer] from [this page][ruby_downloads].
22 2. Run the downloaded file.
23     1. Use the default installation path (usually `C:\Ruby22`).
24     1. Make sure the **'add executable to path'** option is checked.
25 3. Download [this Ruby DevKit self-extracting archive][ruby_devkit] from the [same website][ruby_downloads].
26 4. Run the downloaded file.
27     1. Use the following extraction path: `C:\Ruby22DevKit`.
28 5. Open `cmd.exe`.
29     1. Go to the extraction path:
30
31             cd C:\Ruby22DevKit
32     1. Run these commands (following any instructions they give):
33
34             ruby dk.rb init
35             ruby dk.rb install
36     1. Close `cmd.exe`.
37
38 ### Linux
39
40 Run the commands from [this site][ruby_linux] that apply to your Linux distribution.
41
42 ***
43
44 Verify the installation by running:
45
46     ruby --version
47
48 ## Python
49
50 Python 2.7 is also required to build the docs. NOTE: *The docs will not build with Python 3.0 or greater.*
51
52 ### Mac OS X
53
54 Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:
55
56 1. Download [this installer][python_installer_mac] from [this page][python_downloads].
57 2. Run the downloaded file.
58
59 ### Windows
60
61 Follow these steps:
62
63 1. Download [this installer][python_installer_windows] from [this page][python_downloads].
64 2. Run the downloaded file.
65    1. Use the default installation path
66    1. Make sure the **'add executable to path'** option is checked.
67
68 ### Linux
69
70 The latest version of CentOS, Fedora, Redhat Enterprise (RHEL) and Ubuntu come with Python 2.7 pre-installed. Else, follow the steps from [this site][python_linux].
71
72 ***
73
74 Verify the installation by running:
75
76     python --version
77
78 The version must be 2.7.x.
79
80 ## JavaScript
81
82 ### Mac OS X & Windows
83
84 Go to [this site][nodejs], and click the "Install" button. Then run the downloaded file and follow the on-screen instructions. Make sure that the option to **install NPM** is enabled, if you see one.
85
86 ### Linux
87
88 Linux, follow the instructions on [this site][linux_node].
89
90 ***
91
92 Verify the installation by running:
93
94     node --version
95     npm --version
96
97 ## Dependencies
98
99 Once Ruby and JavaScript are installed, install Ruby dependencies by running:
100
101     gem install bundle
102     bundle install
103
104 On some systems, the above commands need to be prefixed with `sudo`. Similarly on Windows, the `cmd` window in which those commands are to be run might need to have been "Run as Administrator."
105
106 Finally, install JavaScript dependencies by running:
107
108     npm install
109
110 Building
111 ========
112
113 To build the whole website, run:
114
115     node_modules/.bin/gulp build --prod
116
117 The built website will be in a folder called `build-prod`.
118
119 Developing
120 ==========
121
122 To work on the website and see changes live as you save, run:
123
124     node_modules/.bin/gulp serve
125
126 That command will build the site and start a local server. To work on only the website without the docs, add the `--nodocs` flag, as follows:
127
128     node_modules/.bin/gulp serve --nodocs
129
130 Alternatively, to dynamically rebuild the site and refresh the browser _when changes happen_ (again, optionally with the `--nodocs` flag), run:
131
132     node_modules/.bin/gulp watch
133
134 Deploying
135 =========
136
137 This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].
138
139 To build the full website (possibly excluding docs by adding `--nodocs`), run:
140
141     gulp build --prod
142
143 A folder called `build-prod` will be created, and will contain the built website. Then, in a directory *outside* of the `cordova-docs` repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):
144
145     cd ..
146     svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
147
148 Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN like so:
149
150     cp -R cordova-docs/build-prod/. cordova-website/public/
151
152 Finally, go into the `cordova-website` directory and commit *all* the changes introduced by the newly copied files. Some files will be new (`?` in SVN, and need to be `svn add`ed) and some files will be changed (`M` in SVN; no action required). To see just the `?` changes, run:
153
154     svn status | grep "?"
155
156 The commit might take a while (up to 1 hour), depending on the number of files changed.
157
158 Working on the Documentation
159 ============================
160
161 Refer to this [README.md](doc/README/en/README.md) for information about writing documentation.
162
163 Adding a Tool or a Showcase App
164 ===============================
165
166 Items on the **Codorva Tools** or the **Cordova App Showcase** sections on the main page are modifiable by the public. Below are the guidelines and process to do so.
167
168 ## Guidelines
169
170 The display _image_ shall:
171
172 1. be __less than 128KiB__ in size (NOTE: those are kibibytes, not kilobytes),
173 2. contain the __logo__ of the tool/app,
174 3. use __colors that don't compete__ with other elements on the page, and
175 4. have acceptable measurements, as follows:
176     - __298px by 100px__ or smaller with a roughly rectangular aspect ratio for tools, and
177     - __100px by 100px__ or smaller with a square aspect ratio for apps.
178
179 The _description_ shall:
180
181 1. contain __neutral__ and non-advertising language.
182
183 The _name_ shall:
184
185 1. be __at most 40__ characters long.
186
187 Showcase _apps_ shall:
188
189 1. be available for download on a __public app store__ or website.
190
191 Furthermore, descriptions are stripped of HTML and are truncated to fit as follows:
192
193 - down to 255 characters for tools and,
194 - down to 200 characters for showcase apps.
195
196 ## Process
197
198 1. Change the section's YAML file:
199     - [www/_data/tools.yml](www/_data/tools.yml) for Cordova Tools, or
200     - [www/_data/showcase-apps.yml](www/_data/showcase-apps.yml) for Cordova App Showcase.
201 1. Optionally add an image:
202     1. Place the image in the section's `img` directory:
203         - [www/static/img/tools](www/static/img/tools) for Cordova Tools, or
204         - [www/static/img/showcase-apps](www/static/img/showcase-apps) for Cordova App Showcase.
205     1. In the YAML file, set the `image` field to the file's *name*.
206 1. Submit a [GitHub pull request][pr] with the changes.
207
208 Writing a Blog Post
209 ===================
210
211 1. Pull down the latest website codebase for the current posts
212
213         git pull
214
215 2. Create a new entry in the www/_posts directory.
216
217 3. Use an earlier post an a template. Edit your md file to remove undesired markdown links. If there is a phrase in square brackets that isn't a CB-xxxx reference, escape it with backslashes. Otherwise, heruko might error out and fail to build all the html.
218
219         [CB-1234] \[iOS\] \[Camera\] add a whizzbang to the snarfblat
220
221 4. Set a marker where the summary on the home page should stop displaying. Add the following html comment line to your md file at the desired cutoff point:
222
223         <!--more-->
224
225 5. In the front matter of your blog entry, set the `date:` field to the desired date that you want to appear near the title. Be aware that the date (explicit here or implied via the filename) will be used to generate the relative path to this html file (e.g. "/announcements/2014/09/22/cordova-361.html"), as will the `categories:` front matter value.
226
227         date: 2014-09-22
228         categories: announcements
229
230 6. Run gulp link-bugs to linkify
231
232         gulp link-bugs
233
234 7. Preview it locally by running the site using gulp
235
236 8. Raise a Pull Request with the changes
237
238 **Types of Posts**
239
240 _Announcements_ - releases, call for translators, etc
241
242 _Core Content_ - If the content has to do with cordova-core, or publishing guides, etc., we should publish the full text directly on the cordova Blog (by whichever author), as-if written by the organization.
243
244 _Linked Posts_ - If the content was written by a contributor and is worth curating for the whole community, but is not really core ie. non-core plugins, dev tips, research, opinion-pieces, statistics, etc., post a short description, perhaps adding a document-snippet, but then link to the externally hosted content, making it clearly not written by the organization.
245
246 **Post guidelines:**
247
248 * Use the post title as the first header.
249 * Including a header as well makes the snippet on the front page look bad.
250 * Use an appropriate category:
251 * One of: `howto`, `news`, `releases`, `announcements`, `blog` (the catch-all category)
252 * Use appropriate tags:
253 * `tools`, `plugins`, `android`, `ios`, `windowsphone`, `blackberry`, `plugin-$FOO`, `cli`, `performance`, `last-week`, `security` (add to this list as necessary)
254 * Use gulp to preview your posts locally.
255 * Jekyll does a poor job telling you where markdown errors exist.
256 * Use the <!--more--> tag to specify the cutoff point for displaying your post on the main page.
257 * Review your post yourself before asking for a review. This includes spell-check :).
258 * Ask for a review by raising a pull request
259
260 ***Creating "last week" Posts:***
261
262 To get a summary of changes (and count the changes):
263
264     for l in cordova-*; do ( cd $l ; git log --format="$(printf %30s $l) %s" --no-merges --since='1 week ago' ) ; done | grep -iv version | grep -v CHANGELOG > all_logs.txt
265
266 To get the number of authors:
267
268     for l in cordova-*; do ( cd $l ; git log --format="%an" --no-merges --since='1 week ago' ) ; done | sort | uniq | wc -l
269
270 ***Creating Release Announcement Posts***
271
272 Create a copy of a previous post and update it.
273
274 To print the list of plugin versions tested:
275
276 1. Make sure all plugin repos are cloned, updated, and on master branch
277 2. Run:
278
279         for d in *-plugin-*; do ( cd $d && echo "* $(basename $PWD): $(grep version plugin.xml|grep -v encoding|cut -d'"' -f2)" ) ; done | grep '^\*'
280
281 Troubleshooting
282 ===============
283
284 ## Error: EMF, too many open files
285
286 Increase the maximum number of open files on the system:
287
288     ulimit -n 10480
289
290 ## Error: spawn ENOENT
291
292 Run:
293
294     gulp clean
295
296 ## Permission issues during Ruby install
297
298 You could try a different method to install Ruby. Checkout [rbenv][rbenvgh]. Instructions:
299
300 1. Install rbenv
301
302         brew install rbenv ruby-build
303
304 2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
305
306         echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
307
308 3. Install a version of `ruby` and set it to your local version:
309
310         rbenv install 2.0.0-p647
311         rbenv local 2.0.0-p647
312
313 ## Other Problems
314
315 Please ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io/).
316
317 [ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
318 [homebrew]: http://brew.sh/
319 [linux_node]: https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
320 [ruby_downloads]: http://rubyinstaller.org/downloads/
321 [ruby_installer]: http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.2.3.exe
322 [ruby_devkit]: http://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe
323 [nodejs]: https://nodejs.org/
324 [install_pip]: https://pip.pypa.io/en/latest/installing.html
325 [svn]: http://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html
326 [pr]: https://help.github.com/articles/using-pull-requests/
327 [rbenvgh]: https://github.com/sstephenson/rbenv
328 [python_downloads]: https://www.python.org/downloads/release/python-2711/
329 [python_installer_mac]: https://www.python.org/ftp/python/2.7.11/python-2.7.11-macosx10.6.pkg
330 [python_installer_windows]: https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi
331 [python_linux]: http://docs.python-guide.org/en/latest/starting/install/linux/