<commit_before>Introduction
============

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)).

Installing
==========

## Ruby

Ruby 1.8, 1.9 and 2.4 are confirmed _not_ to work. Please make sure you are running ruby 2.0.

### Mac OS X

Install Homebrew from [this site][homebrew], and then run:

    brew install ruby@2.0

### Windows

Follow these steps:

1. Download [this installer][ruby_installer] from [this page][ruby_downloads].
2. Run the downloaded file.
    1. Use the default installation path (usually `C:\Ruby22`).
    1. Make sure the **'add executable to path'** option is checked.
3. Download [this Ruby DevKit self-extracting archive][ruby_devkit] from the [same website][ruby_downloads].
4. Run the downloaded file.
    1. Use the following extraction path: `C:\Ruby22DevKit`.
5. Open `cmd.exe`.
    1. Go to the extraction path:

            cd C:\Ruby22DevKit
    1. Run these commands (following any instructions they give):

            ruby dk.rb init
            ruby dk.rb install
    1. Close `cmd.exe`.

### Linux

Run the commands from [this site][ruby_linux] that apply to your Linux distribution.

***

Verify the installation by running:

    ruby --version

## Python

Python 2.7 is also required to build the docs. NOTE: *The docs will not build with Python 3.0 or greater.*

### Mac OS X

Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:

1. Download [this installer][python_installer_mac] from [this page][python_downloads].
2. Run the downloaded file.

### Windows

Follow these steps:

1. Download [this installer][python_installer_windows] from [this page][python_downloads].
2. Run the downloaded file.
   1. Use the default installation path
   1. Make sure the **'add executable to path'** option is checked.

### Linux

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].

***

Verify the installation by running:

    python --version

The version must be 2.7.x.

## JavaScript

### Mac OS X &amp; Windows

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.

### Linux

Linux, follow the instructions on [this site][linux_node].

***

Verify the installation by running:

    node --version
    npm --version

## Dependencies

Once Ruby and JavaScript are installed, install Ruby dependencies by running:

    gem install bundler
    bundle install --path ./ruby_modules

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."

Finally, install JavaScript dependencies by running:

    npm install

## Make (optional)

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.

### Windows

Make can be installed on Windows from [this page][make_page] by downloading the [setup tool][make_setup] and running it.

### OS X

Make comes with the Xcode Command Line Tools. To install them, run:

    xcode-select --install

### Linux

Make is installed by default on Linux.

***

Verify the installation by running:

    make --version

Building
========

To build the whole website, run:

    node_modules/.bin/gulp build --prod

The built website will be in a folder called `build-prod`.

Developing
==========

To work on the website and see changes live as you save, run:

    node_modules/.bin/gulp serve

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:

    node_modules/.bin/gulp serve --nodocs

Alternatively, to dynamically rebuild the site and refresh the browser _when changes happen_ (again, optionally with the `--nodocs` flag), run:

    node_modules/.bin/gulp watch

## Docs Redirects

Sometimes docs pages get removed, renamed, and added. There is [a file][redirects] that contains redirects for such occasions. It has three sections:

- `docs-global`: redirects across all docs versions and languages,
- `docs`: version-specific docs redirects, and
- `general`: single-page redirects.

For non-docs URIs, there are no versioning considerations. Make redirects like so:

    general:
        - {old: "old/uri/for/page.html", new: "its/new/uri.html"}

**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.

There are five cases of changing URIs:

1. Adding a brand new (no past equivalent) URI starting at a version,
2. Removing an old URI (with no replacement) starting at a version,
3. Renaming (removing and adding) an existing URI starting at a version,
4. Renaming an existing URI across all versions,
5. Removing an existing URI across all versions.

### Case 1: Adding a URI starting at a version

Do nothing. Going back in time for new docs is unsupported.

### Cases 2 &amp; 3: Removing or renaming a URI starting at a version

If the URI is removed, mark it as deprecated in `latest/` like so:

    docs:
        - {old: "latest/old/uri/for/page.html", new: "deprecated.html"}

If the URI is moved, point it to its new location in `latest/` like so:

    docs:
        - {old: "latest/old/uri/for/page.html", new: "latest/its/new/uri.html"}

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.

### Case 4: Renaming a URI across all versions

Add the redirect (in the `docs-global` section this time) like so:

    docs-global:
        - {old: "old/uri/for/page.html", new: "its/new/uri.html"}

### Case 5: Removing a URI across all versions

Do nothing. It is now an un-URI. It never existed. Mentioning it is thoughtcrime.

Deploying
=========

This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].

To build the full website and preview it in your browser, run:

    npm run serve

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):

    cd ..
    svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
(Make sure to `svn checkout` on the same level that `cordova-docs` repo exists on.)

From the `cordova-website` repo, run the following command:
    
    svn up

Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN like so:

    cp -R cordova-docs/build-prod/. cordova-website/public/

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:

    svn status | grep "?"

Once you are satisfied that you have added the required changes, commit with a message:

    svn commit -m "Updated docs"


The commit might take a while (up to 1 hour), depending on the number of files changed.
<commit_msg>Fixed up 'deployment' docs in README.md. Restored 'gulp build' command in lieu of 'npm run serve' command. Tested and fixed suggested deployment commands. Removed redundant text.<commit_after>Introduction
============

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)).

Installing
==========

## Ruby

Ruby 1.8, 1.9 and 2.4 are confirmed _not_ to work. Please make sure you are running ruby 2.0.

### Mac OS X

Install Homebrew from [this site][homebrew], and then run:

    brew install ruby@2.0

### Windows

Follow these steps:

1. Download [this installer][ruby_installer] from [this page][ruby_downloads].
2. Run the downloaded file.
    1. Use the default installation path (usually `C:\Ruby22`).
    1. Make sure the **'add executable to path'** option is checked.
3. Download [this Ruby DevKit self-extracting archive][ruby_devkit] from the [same website][ruby_downloads].
4. Run the downloaded file.
    1. Use the following extraction path: `C:\Ruby22DevKit`.
5. Open `cmd.exe`.
    1. Go to the extraction path:

            cd C:\Ruby22DevKit
    1. Run these commands (following any instructions they give):

            ruby dk.rb init
            ruby dk.rb install
    1. Close `cmd.exe`.

### Linux

Run the commands from [this site][ruby_linux] that apply to your Linux distribution.

***

Verify the installation by running:

    ruby --version

## Python

Python 2.7 is also required to build the docs. NOTE: *The docs will not build with Python 3.0 or greater.*

### Mac OS X

Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:

1. Download [this installer][python_installer_mac] from [this page][python_downloads].
2. Run the downloaded file.

### Windows

Follow these steps:

1. Download [this installer][python_installer_windows] from [this page][python_downloads].
2. Run the downloaded file.
   1. Use the default installation path
   1. Make sure the **'add executable to path'** option is checked.

### Linux

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].

***

Verify the installation by running:

    python --version

The version must be 2.7.x.

## JavaScript

### Mac OS X &amp; Windows

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.

### Linux

Linux, follow the instructions on [this site][linux_node].

***

Verify the installation by running:

    node --version
    npm --version

## Dependencies

Once Ruby and JavaScript are installed, install Ruby dependencies by running:

    gem install bundler
    bundle install --path ./ruby_modules

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."

Finally, install JavaScript dependencies by running:

    npm install

## Make (optional)

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.

### Windows

Make can be installed on Windows from [this page][make_page] by downloading the [setup tool][make_setup] and running it.

### OS X

Make comes with the Xcode Command Line Tools. To install them, run:

    xcode-select --install

### Linux

Make is installed by default on Linux.

***

Verify the installation by running:

    make --version

Building
========

To build the whole website, run:

    node_modules/.bin/gulp build --prod

The built website will be in a folder called `build-prod`.

Developing
==========

To work on the website and see changes live as you save, run:

    node_modules/.bin/gulp serve

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:

    node_modules/.bin/gulp serve --nodocs

Alternatively, to dynamically rebuild the site and refresh the browser _when changes happen_ (again, optionally with the `--nodocs` flag), run:

    node_modules/.bin/gulp watch

## Docs Redirects

Sometimes docs pages get removed, renamed, and added. There is [a file][redirects] that contains redirects for such occasions. It has three sections:

- `docs-global`: redirects across all docs versions and languages,
- `docs`: version-specific docs redirects, and
- `general`: single-page redirects.

For non-docs URIs, there are no versioning considerations. Make redirects like so:

    general:
        - {old: "old/uri/for/page.html", new: "its/new/uri.html"}

**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.

There are five cases of changing URIs:

1. Adding a brand new (no past equivalent) URI starting at a version,
2. Removing an old URI (with no replacement) starting at a version,
3. Renaming (removing and adding) an existing URI starting at a version,
4. Renaming an existing URI across all versions,
5. Removing an existing URI across all versions.

### Case 1: Adding a URI starting at a version

Do nothing. Going back in time for new docs is unsupported.

### Cases 2 &amp; 3: Removing or renaming a URI starting at a version

If the URI is removed, mark it as deprecated in `latest/` like so:

    docs:
        - {old: "latest/old/uri/for/page.html", new: "deprecated.html"}

If the URI is moved, point it to its new location in `latest/` like so:

    docs:
        - {old: "latest/old/uri/for/page.html", new: "latest/its/new/uri.html"}

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.

### Case 4: Renaming a URI across all versions

Add the redirect (in the `docs-global` section this time) like so:

    docs-global:
        - {old: "old/uri/for/page.html", new: "its/new/uri.html"}

### Case 5: Removing a URI across all versions

Do nothing. It is now an un-URI. It never existed. Mentioning it is thoughtcrime.

Deploying
=========

This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].

To build the full website and preview it in your browser, run:

    node_modules/.bin/gulp build --prod

A folder called `build-prod` will be created, and will contain the built website. Then, in a directory *one level above* the `cordova-docs` repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):

    cd ..
    svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website

Then, move into the `cordova-website` repository and synchronise it with the SVN server:

    cd cordova-website
    svn update

Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN like so:

    cd ..
    cp -R cordova-docs/build-prod/. cordova-website/public/

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:

    cd cordova-website
    svn status | grep "?"

Once you are satisfied that you have added the required changes, commit with a message:

    svn commit -m "Updated docs"

**NOTE**: The commit might take a while (up to 1 hour), depending on the number of files changed.

{'fraction_non_alphanumeric': 0.09006957621758381, 'fraction_numerical': 0.007210626185958254, 'mean_word_length': 3.6875185294989623, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 30, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1904676', 'n_tokens_mistral': 4657, 'n_tokens_neox': 4350, 'n_words': 2188}