718f79d1d3c57c1d6c9d2feef02a4fc6610a3ad0
[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 ## Make (optional)
111
112 The website can be built with Gulp or Make. The Gulp workflow is enabled by just installing all the JavaScript dependencies. The Make workflow usually allows for faster builds, but requires installation of the `make` tool.
113
114 ### Windows
115
116 Make can be installed on Windows from [this page][make_page] by downloading the [setup tool][make_setup] and running it.
117
118 ### OS X
119
120 Make comes with the Xcode Command Line Tools. To install them, run:
121
122     xcode-select --install
123
124 ### Linux
125
126 Make is installed by default on Linux.
127
128 ***
129
130 Verify the installation by running:
131
132     make --version
133
134 Building
135 ========
136
137 To build the whole website, run:
138
139     node_modules/.bin/gulp build --prod
140
141 The built website will be in a folder called `build-prod`.
142
143 Developing
144 ==========
145
146 To work on the website and see changes live as you save, run:
147
148     node_modules/.bin/gulp serve
149
150 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:
151
152     node_modules/.bin/gulp serve --nodocs
153
154 Alternatively, to dynamically rebuild the site and refresh the browser _when changes happen_ (again, optionally with the `--nodocs` flag), run:
155
156     node_modules/.bin/gulp watch
157
158 ## Docs Redirects
159
160 Sometimes docs pages get removed, renamed, and added. There is [a file][redirects] that contains redirects for such occasions. It has three sections:
161
162 - `docs-global`: redirects across all docs versions and languages,
163 - `docs`: version-specific docs redirects, and
164 - `general`: single-page redirects.
165
166 For non-docs URIs, there are no versioning considerations. Make redirects like so:
167
168     general:
169         - {old: "old/uri/for/page.html", new: "its/new/uri.html"}
170
171 **NOTE**: Review (and test, if possible) these redirects before making them live, since they're permanent (HTTP 301) redirects. Incorrect permanent redirects will make a URI almost impossible to bring back into browsers and search indices.
172
173 There are five cases of changing URIs:
174
175 1. Adding a brand new (no past equivalent) URI starting at a version,
176 2. Removing an old URI (with no replacement) starting at a version,
177 3. Renaming (removing and adding) an existing URI starting at a version,
178 4. Renaming an existing URI across all versions,
179 5. Removing an existing URI across all versions.
180
181 ### Case 1: Adding a URI starting at a version
182
183 Do nothing. Going back in time for new docs is unsupported.
184
185 ### Cases 2 & 3: Removing or renaming a URI starting at a version
186
187 If the URI is removed, mark it as deprecated in `latest/` like so:
188
189     docs:
190         - {old: "latest/old/uri/for/page.html", new: "deprecated.html"}
191
192 If the URI is moved, point it to its new location in `latest/` like so:
193
194     docs:
195         - {old: "latest/old/uri/for/page.html", new: "latest/its/new/uri.html"}
196
197 These will handle the case where the "this content is outdated" link is clicked. The case where a user jumps to a specific version is not yet supported.
198
199 ### Case 4: Renaming a URI across all versions
200
201 Add the redirect (in the `docs-global` section this time) like so:
202
203     docs-global:
204         - {old: "old/uri/for/page.html", new: "its/new/uri.html"}
205
206 ### Case 5: Removing a URI across all versions
207
208 Do nothing. It is now an un-URI. It never existed. Mentioning it is thoughtcrime.
209
210 Deploying
211 =========
212
213 This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].
214
215 To build the full website (possibly excluding docs by adding `--nodocs`), run:
216
217     gulp build --prod
218
219 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):
220
221     cd ..
222     svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
223
224 Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN like so:
225
226     cp -R cordova-docs/build-prod/. cordova-website/public/
227
228 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:
229
230     svn status | grep "?"
231
232 The commit might take a while (up to 1 hour), depending on the number of files changed.
233
234 Working on the Documentation
235 ============================
236
237 Refer to this [README.md](doc/README/en/README.md) for information about writing documentation.
238
239 Adding a Tool or a Showcase App
240 ===============================
241
242 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.
243
244 ## Guidelines
245
246 The display _image_ shall:
247
248 1. be __less than 128KiB__ in size (NOTE: those are kibibytes, not kilobytes),
249 2. contain the __logo__ of the tool/app,
250 3. use __colors that don't compete__ with other elements on the page, and
251 4. have acceptable measurements, as follows:
252     - __298px by 100px__ or smaller with a roughly rectangular aspect ratio for tools, and
253     - __100px by 100px__ or smaller with a square aspect ratio for apps.
254
255 The _description_ shall:
256
257 1. contain __neutral__ and non-advertising language.
258
259 The _name_ shall:
260
261 1. be __at most 40__ characters long.
262
263 Showcase _apps_ shall:
264
265 1. be available for download on a __public app store__ or website.
266
267 Furthermore, descriptions are stripped of HTML and are truncated to fit as follows:
268
269 - down to 255 characters for tools and,
270 - down to 200 characters for showcase apps.
271
272 ## Process
273
274 1. Change the section's YAML file:
275     - [www/_data/tools.yml](www/_data/tools.yml) for Cordova Tools, or
276     - [www/_data/showcase-apps.yml](www/_data/showcase-apps.yml) for Cordova App Showcase.
277 1. Optionally add an image:
278     1. Place the image in the section's `img` directory:
279         - [www/static/img/tools](www/static/img/tools) for Cordova Tools, or
280         - [www/static/img/showcase-apps](www/static/img/showcase-apps) for Cordova App Showcase.
281     1. In the YAML file, set the `image` field to the file's *name*.
282 1. Submit a [GitHub pull request][pr] with the changes.
283
284 Writing a Blog Post
285 ===================
286
287 1. Pull down the latest website codebase for the current posts
288
289         git pull
290
291 2. Create a new entry in the www/_posts directory.
292
293 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.
294
295         [CB-1234] \[iOS\] \[Camera\] add a whizzbang to the snarfblat
296
297 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:
298
299         <!--more-->
300
301 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.
302
303         date: 2014-09-22
304         categories: announcements
305
306 6. Run gulp link-bugs to linkify
307
308         gulp link-bugs
309
310 7. Preview it locally by running the site using gulp
311
312 8. Raise a Pull Request with the changes
313
314 **Types of Posts**
315
316 _Announcements_ - releases, call for translators, etc
317
318 _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.
319
320 _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.
321
322 **Post guidelines:**
323
324 * Use the post title as the first header.
325 * Including a header as well makes the snippet on the front page look bad.
326 * Use an appropriate category:
327 * One of: `howto`, `news`, `releases`, `announcements`, `blog` (the catch-all category)
328 * Use appropriate tags:
329 * `tools`, `plugins`, `android`, `ios`, `windowsphone`, `blackberry`, `plugin-$FOO`, `cli`, `performance`, `last-week`, `security` (add to this list as necessary)
330 * Use gulp to preview your posts locally.
331 * Jekyll does a poor job telling you where markdown errors exist.
332 * Use the <!--more--> tag to specify the cutoff point for displaying your post on the main page.
333 * Review your post yourself before asking for a review. This includes spell-check :).
334 * Ask for a review by raising a pull request
335
336 ***Creating "last week" Posts:***
337
338 To get a summary of changes (and count the changes):
339
340     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
341
342 To get the number of authors:
343
344     for l in cordova-*; do ( cd $l ; git log --format="%an" --no-merges --since='1 week ago' ) ; done | sort | uniq | wc -l
345
346 ***Creating Release Announcement Posts***
347
348 Create a copy of a previous post and update it.
349
350 To print the list of plugin versions tested:
351
352 1. Make sure all plugin repos are cloned, updated, and on master branch
353 2. Run:
354
355         for d in *-plugin-*; do ( cd $d && echo "* $(basename $PWD): $(grep version plugin.xml|grep -v encoding|cut -d'"' -f2)" ) ; done | grep '^\*'
356
357 Troubleshooting
358 ===============
359
360 ## Error: EMF, too many open files
361
362 Increase the maximum number of open files on the system:
363
364     ulimit -n 10480
365
366 ## Error: spawn ENOENT
367
368 Run:
369
370     gulp clean
371
372 ## Permission issues during Ruby install
373
374 You could try a different method to install Ruby. Checkout [rbenv][rbenvgh]. Instructions:
375
376 1. Install rbenv
377
378         brew install rbenv ruby-build
379
380 2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
381
382         echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
383
384 3. Install a version of `ruby` and set it to your local version:
385
386         rbenv install 2.0.0-p647
387         rbenv local 2.0.0-p647
388
389 ## Other Problems
390
391 Please ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io/).
392
393 Attributions
394 ============
395
396 For attributions for used open-source work, please see the attributions page: `www/attributions.html`.
397
398 [ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
399 [homebrew]: http://brew.sh/
400 [linux_node]: https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
401 [ruby_downloads]: http://rubyinstaller.org/downloads/
402 [ruby_installer]: http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.2.3.exe
403 [ruby_devkit]: http://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe
404 [nodejs]: https://nodejs.org/
405 [install_pip]: https://pip.pypa.io/en/latest/installing.html
406 [svn]: http://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html
407 [pr]: https://help.github.com/articles/using-pull-requests/
408 [rbenvgh]: https://github.com/sstephenson/rbenv
409 [python_downloads]: https://www.python.org/downloads/release/python-2711/
410 [python_installer_mac]: https://www.python.org/ftp/python/2.7.11/python-2.7.11-macosx10.6.pkg
411 [python_installer_windows]: https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi
412 [python_linux]: http://docs.python-guide.org/en/latest/starting/install/linux/
413 [redirects]: www/_docs/redirects.yml
414 [make_page]: http://gnuwin32.sourceforge.net/packages/make.htm
415 [make_setup]: http://gnuwin32.sourceforge.net/downlinks/make.php