578fc1cefb13b473c3073de8377898737269cc09
[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 > Note: many changes to the overall documentation come from other repos and are simply pulled together by a build.  tools/bin/fetch_docs.js has more details and www/_data/fetched-files.yml contains an informative list of src/dest pairs.  Most auto-generated files have a comment tag at the top of the file to indicate that they come from elsewhere.
240
241 Adding a Tool or a Showcase App
242 ===============================
243
244 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.
245
246 ## Guidelines
247
248 The display _image_ shall:
249
250 1. be __less than 128KiB__ in size (NOTE: those are kibibytes, not kilobytes),
251 2. contain the __logo__ of the tool/app,
252 3. use __colors that don't compete__ with other elements on the page, and
253 4. have acceptable measurements, as follows:
254     - __298px by 100px__ or smaller with a roughly rectangular aspect ratio for tools, and
255     - __100px by 100px__ or smaller with a square aspect ratio for apps.
256
257 The _description_ shall:
258
259 1. contain __neutral__ and non-advertising language.
260
261 The _name_ shall:
262
263 1. be __at most 40__ characters long.
264
265 Showcase _apps_ shall:
266
267 1. be available for download on a __public app store__ or website.
268
269 Furthermore, descriptions are stripped of HTML and are truncated to fit as follows:
270
271 - down to 255 characters for tools and,
272 - down to 200 characters for showcase apps.
273
274 ## Process
275
276 1. Change the section's YAML file:
277     - [www/_data/tools.yml](www/_data/tools.yml) for Cordova Tools, or
278     - [www/_data/showcase-apps.yml](www/_data/showcase-apps.yml) for Cordova App Showcase.
279 1. Optionally add an image:
280     1. Place the image in the section's `img` directory:
281         - [www/static/img/tools](www/static/img/tools) for Cordova Tools, or
282         - [www/static/img/showcase-apps](www/static/img/showcase-apps) for Cordova App Showcase.
283     1. In the YAML file, set the `image` field to the file's *name*.
284 1. Submit a [GitHub pull request][pr] with the changes.
285
286 Writing a Blog Post
287 ===================
288
289 1. Pull down the latest website codebase for the current posts
290
291         git pull
292
293 2. Create a new entry in the www/_posts directory.
294
295 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.
296
297         [CB-1234] \[iOS\] \[Camera\] add a whizzbang to the snarfblat
298
299 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:
300
301         <!--more-->
302
303 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.
304
305         date: 2014-09-22
306         categories: announcements
307
308 6. Run gulp link-bugs to linkify
309
310         gulp link-bugs
311
312 7. Preview it locally by running the site using gulp
313
314 8. Raise a Pull Request with the changes
315
316 **Types of Posts**
317
318 _Announcements_ - releases, call for translators, etc
319
320 _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.
321
322 _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.
323
324 **Post guidelines:**
325
326 * Use the post title as the first header.
327 * Including a header as well makes the snippet on the front page look bad.
328 * Use an appropriate category:
329 * One of: `howto`, `news`, `releases`, `announcements`, `blog` (the catch-all category)
330 * Use appropriate tags:
331 * `tools`, `plugins`, `android`, `ios`, `windowsphone`, `blackberry`, `plugin-$FOO`, `cli`, `performance`, `last-week`, `security` (add to this list as necessary)
332 * Use gulp to preview your posts locally.
333 * Jekyll does a poor job telling you where markdown errors exist.
334 * Use the <!--more--> tag to specify the cutoff point for displaying your post on the main page.
335 * Review your post yourself before asking for a review. This includes spell-check :).
336 * Ask for a review by raising a pull request
337
338 ***Creating "last week" Posts:***
339
340 To get a summary of changes (and count the changes):
341
342     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
343
344 To get the number of authors:
345
346     for l in cordova-*; do ( cd $l ; git log --format="%an" --no-merges --since='1 week ago' ) ; done | sort | uniq | wc -l
347
348 ***Creating Release Announcement Posts***
349
350 Create a copy of a previous post and update it.
351
352 To print the list of plugin versions tested:
353
354 1. Make sure all plugin repos are cloned, updated, and on master branch
355 2. Run:
356
357         for d in *-plugin-*; do ( cd $d && echo "* $(basename $PWD): $(grep version plugin.xml|grep -v encoding|cut -d'"' -f2)" ) ; done | grep '^\*'
358
359 Troubleshooting
360 ===============
361
362 ## Error: EMF, too many open files
363
364 Increase the maximum number of open files on the system:
365
366     ulimit -n 10480
367
368 ## Error: spawn ENOENT
369
370 Run:
371
372     gulp clean
373
374 ## Permission issues during Ruby install
375
376 You could try a different method to install Ruby. Checkout [rbenv][rbenvgh]. Instructions:
377
378 1. Install rbenv
379
380         brew install rbenv ruby-build
381
382 2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
383
384         echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
385
386 3. Install a version of `ruby` and set it to your local version:
387
388         rbenv install 2.0.0-p647
389         rbenv local 2.0.0-p647
390
391 ## Other Problems
392
393 Please ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io/).
394
395 Attributions
396 ============
397
398 For attributions for used open-source work, please see the attributions page: `www/attributions.html`.
399
400 [ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
401 [homebrew]: http://brew.sh/
402 [linux_node]: https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
403 [ruby_downloads]: http://rubyinstaller.org/downloads/
404 [ruby_installer]: http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.2.3.exe
405 [ruby_devkit]: http://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe
406 [nodejs]: https://nodejs.org/
407 [install_pip]: https://pip.pypa.io/en/latest/installing.html
408 [svn]: http://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html
409 [pr]: https://help.github.com/articles/using-pull-requests/
410 [rbenvgh]: https://github.com/sstephenson/rbenv
411 [python_downloads]: https://www.python.org/downloads/release/python-2711/
412 [python_installer_mac]: https://www.python.org/ftp/python/2.7.11/python-2.7.11-macosx10.6.pkg
413 [python_installer_windows]: https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi
414 [python_linux]: http://docs.python-guide.org/en/latest/starting/install/linux/
415 [redirects]: www/_docs/redirects.yml
416 [make_page]: http://gnuwin32.sourceforge.net/packages/make.htm
417 [make_setup]: http://gnuwin32.sourceforge.net/downlinks/make.php