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