This is an automated email from the ASF dual-hosted git repository.
erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 5181dcb593 fix: use Ruby 3.4 for website builds, update documentation
(#1544)
5181dcb593 is described below
commit 5181dcb593f0990356f66281ddb89f0a445c3441
Author: Manuel Beck <[email protected]>
AuthorDate: Mon Nov 9 05:22:30 2026 +0100
fix: use Ruby 3.4 for website builds, update documentation (#1544)
* fix: use Ruby 3.4 for website builds
Generated-by: OpenAI Codex (GPT-6.1 Sol)
* docs: preserve title capitalization in setup guide
Generated-by: OpenAI Codex (GPT-6.1 Sol)
* docs: capitalize every word in headings
Generated-by: OpenAI Codex (GPT-6.1 Sol)
* docs: lowercase minor words in headings
Generated-by: OpenAI Codex (GPT-6.1 Sol)
---
.github/workflows/ci.yml | 2 +-
.github/workflows/deploy-prod.yml | 2 +-
.github/workflows/deploy-stage.yml | 2 +-
README.md | 13 ++-
doc/building-and-deploying-the-website.md | 13 +--
doc/deploying-the-website.md | 2 +-
doc/installing-a-development-environment.md | 149 +++++++---------------------
7 files changed, 54 insertions(+), 129 deletions(-)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5079825bce..a5b9fc8069 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -41,7 +41,7 @@ jobs:
- uses: ruby/setup-ruby@e81a8fa391b11a595c1b7ed84177cc0fe02faf83 #
v1.328.0
with:
- ruby-version: 2.7
+ ruby-version: '3.4'
bundler-cache: true
- name: Run npm install-ci-test (cit)
diff --git a/.github/workflows/deploy-prod.yml
b/.github/workflows/deploy-prod.yml
index 5d17d33300..168b5b3367 100644
--- a/.github/workflows/deploy-prod.yml
+++ b/.github/workflows/deploy-prod.yml
@@ -39,7 +39,7 @@ jobs:
- uses: ruby/setup-ruby@e81a8fa391b11a595c1b7ed84177cc0fe02faf83 #
v1.328.0
with:
- ruby-version: 2.7
+ ruby-version: '3.4'
bundler-cache: true
- name: Run npm install-ci-test (cit)
diff --git a/.github/workflows/deploy-stage.yml
b/.github/workflows/deploy-stage.yml
index 03a09dfd10..f2feb7a271 100644
--- a/.github/workflows/deploy-stage.yml
+++ b/.github/workflows/deploy-stage.yml
@@ -44,7 +44,7 @@ jobs:
- uses: ruby/setup-ruby@e81a8fa391b11a595c1b7ed84177cc0fe02faf83 #
v1.328.0
with:
- ruby-version: 2.7
+ ruby-version: '3.4'
bundler-cache: true
- name: Run npm install-ci-test (cit)
diff --git a/README.md b/README.md
index 8d512815c3..0ac82b7ed0 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,7 @@
-[](https://travis-ci.org/apache/cordova-docs)
+[](https://github.com/apache/cordova-docs/actions/workflows/ci.yml)
+[](https://github.com/apache/cordova-docs/actions/workflows/deploy-stage.yml)
+[](https://github.com/apache/cordova-docs/actions/workflows/deploy-prod.yml)
+[](https://github.com/apache/cordova-docs/actions/workflows/release-audit.yml)
# Cordova Docs / Website
@@ -9,9 +12,11 @@ This repository contains the source code for the Cordova
website at [cordova.apa
The main parts are built as a static site with [Jekyll](http://jekyllrb.com/),
containing the homepage and subpages, the
[blog](https://cordova.apache.org/blog) and the
[docs](https://cordova.apache.org/docs).
Here in the repository the code of the actual site is located in [`/www`](www)
with its subfolder [`/docs`](www/docs), [`/blog`](www/blog) and
[`/plugins`](www/plugins).
-Some additional content is [pulled in during the build process](TODO).
+Some additional content is [pulled in during the build
process](www/_data/fetched-files.yml).
-The site is built using a [gulp script](gulpfile.js) that is run by Node.JS
(`npm run-script build`). (Alternatively you can build the site using Make.)
Deployments usually happen on commits to `master` via Travis, which runs
[`buildAndDeploy.sh`](buildAndDeploy.sh) and commits the built site to a SVN
repository.
+The site is built using a [gulp script](gulpfile.js) run by Node.js (`npm run
build`). Development uses **Ruby 3.4.x** and **Node.js 24.x**, matching the
GitHub Actions workflows. See the [installation
guide](doc/installing-a-development-environment.md) for setup instructions.
+
+The [staging workflow](.github/workflows/deploy-stage.yml) builds and deploys
commits to `master` to the `asf-staging` branch. The [production
workflow](.github/workflows/deploy-prod.yml) is started manually and deploys to
`asf-site`. Both run `npm run build:prod`.
## Instructions
@@ -20,7 +25,7 @@ The site is built using a [gulp script](gulpfile.js) that is
run by Node.JS (`np
* [Docs Redirects](doc/redirects.md)
- [Testing](doc/testing-the-website.md)
- Manual [Build](doc/building-the-website.md) and
[Deployment](doc/deploying-the-website.md)
-- [Automated Build and Deployment](doc/building-and-deploying-the-website.md)
on commits/merges to `master` via Travis
+- [Automated Build and Deployment](doc/building-and-deploying-the-website.md)
with GitHub Actions
- [Troubleshooting](doc/troubleshooting.md)
### Common Tasks
diff --git a/doc/building-and-deploying-the-website.md
b/doc/building-and-deploying-the-website.md
index d815ea1269..47a7a59651 100644
--- a/doc/building-and-deploying-the-website.md
+++ b/doc/building-and-deploying-the-website.md
@@ -1,14 +1,11 @@
## Building and Deploying (Automated)
-[Travis] automatically builds and publishes commits to `master` of this
repository, so either merged Pull Requests or direct commits.
+GitHub Actions builds and deploys the website using Ruby 3.4.x and Node.js
24.x.
-In [`.travis.yml`](../.travis.yml), Travis installs the required dependencies
and then runs `buildAndDeploy.sh`. This script runs the build script (`npm
run-script build`, which runs `gulp build --prod`) and then then uses [SVN] to
update, copy, add, and commit the new changes over to the website SVN
repository.
+The [staging workflow](../.github/workflows/deploy-stage.yml) runs
automatically on pushes to `master` and can also be started manually. The
[production workflow](../.github/workflows/deploy-prod.yml) is started
manually. Both check out `master`.
-You can read more about the individual steps [here](deploying-the-website.md).
+Each deployment workflow installs Ruby dependencies with Bundler, runs `npm
install-ci-test` to install the locked Node.js dependencies and run the checks,
then runs `npm run build:prod`.
-Travis also runs `npm test` and will notify you if any of your `eslint` or
`mocha` tests are failing.
+The generated `build-prod` directory is committed to `asf-staging` for staging
or `asf-site` for production. The existing `archive` directory is preserved
during deployment.
-**NOTE**: Committing to Travis might take a while (up to 1 hour), depending on
the number of files changed.
-
-[Travis]: https://travis-ci.org/
-[SVN]: https://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html
+The [PR workflow](../.github/workflows/ci.yml) runs the checks and a
development build for pull requests.
diff --git a/doc/deploying-the-website.md b/doc/deploying-the-website.md
index 923185ad57..63499105da 100644
--- a/doc/deploying-the-website.md
+++ b/doc/deploying-the-website.md
@@ -2,7 +2,7 @@
### Automatic Deployment
-See
[building-and-deploying-the-website.md](building-and-deploying-the-website.md)
for a description of the automated build and deploy process via Travis.
+See
[building-and-deploying-the-website.md](building-and-deploying-the-website.md)
for a description of the automated build and deploy process via GitHub Actions.
### Manual Deployment
diff --git a/doc/installing-a-development-environment.md
b/doc/installing-a-development-environment.md
index 174cbe8985..418373c41b 100644
--- a/doc/installing-a-development-environment.md
+++ b/doc/installing-a-development-environment.md
@@ -1,162 +1,85 @@
## Installing
-The development environment setup requires installation of the following
software:
+The development environment requires:
-1. Ruby - Needed by Jekyll. Jekyll is the static site generator that generates
the website and docs.
-1. Node.js - Needs to be installed in order to install all the required
development and JavaScript dependencies.
-1. Python - Neeeded by Jekyll dependencies like Pygments.
+1. Ruby 3.4.x and Bundler - needed by Jekyll, which generates the website and
docs.
+2. Node.js and npm - needed for the build tools and JavaScript dependencies.
The workflows use Node.js 24.x; see `package.json` for the minimum supported
version.
-### Mac OS X
+### macOS
-#### Ruby
+Install [Homebrew][homebrew], then install Ruby 3.4:
-Install Homebrew from [this site][homebrew], and then run:
+ brew install [email protected]
- brew install [email protected]
+Add its executables to your shell's `PATH` before any other Ruby installation:
-#### Node.js
+ export PATH="$(brew --prefix [email protected])/bin:$PATH"
-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.
-
-#### Python
-
-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.
+Add that line to your shell startup file to keep the setting in new terminals.
+Install Node.js 24.x from [nodejs.org][nodejs].
### Windows
-#### Ruby
-
-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`.
-
-#### Node.js
+Download a **Ruby+Devkit 3.4.x** installer from
[RubyInstaller][ruby_downloads].
+Enable the option to add Ruby executables to `PATH` and complete the MSYS2
development toolchain installation when prompted. This toolchain is needed to
compile native gem extensions.
-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.
-
-#### Python
-
-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.
+Install Node.js 24.x from [nodejs.org][nodejs], including npm.
+Open a new terminal after installing Ruby and Node.js.
### Linux
-#### Ruby
-
-Run the commands from [this site][ruby_linux] that apply to your Linux
distribution.
+Install Ruby 3.4.x using a version manager or the appropriate method from the
[Ruby installation guide][ruby_linux]. Include the development tools needed to
compile native gem extensions.
-#### Node.js
-
-Follow the instructions on [this site][linux_node].
-
-#### Python
-
-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].
+Install Node.js 24.x using the instructions on [nodejs.org][nodejs].
### Check Installations
-#### Verify Ruby
-
-Ruby 2.0 is required to build the docs. NOTE: *The docs will not build with
Ruby 1.8, 1.9 or 2.4.*
-
-Verify your Ruby installation by running:
+Verify that the active Ruby version is 3.4.x:
ruby --version
-#### Verify Node.js
-
-Verify your Node.js installation by running:
+Verify Node.js and npm:
node --version
npm --version
-#### Verify Python
-
-Python 2.7 is also required to build the docs. NOTE: *The docs will not build
with Python 3.0 or greater.*
-
-Verify your Python installation by running:
+### Local Repository Setup
- python --version
-
-The version must be 2.7.x.
-
-### Local repo setup
-
-Clone the [cordova-docs] GitHub repo to a local folder.
+Clone the [cordova-docs] repository and navigate to its directory.
### Dependencies
-#### Ruby
-
-Once Ruby and Node.js are installed, navigate to local repo folder and install
Ruby dependencies by running:
+Install Bundler and the Ruby dependencies:
gem install bundler
- bundle install --path ./ruby_modules
+ bundle config set --local path ./ruby_modules
+ bundle install
-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."
+This installs the gems into `ruby_modules` in the repository. The local
Bundler configuration is stored in `.bundle/config`; both directories are
ignored by Git.
-#### JavaScript
+Install the locked JavaScript dependencies:
-Finally, install Node.js and JavaScript dependencies by running:
+ npm ci
- npm install
+### Verify the Setup
-### Troubleshooting
-
-#### SSL certificate issue while executing `gem install bundler` on Windows
-
-Try copying the certificate from [GlobalSignRootCerficateAuthority] into
`C:\Ruby22\lib\ruby\2.2.0\rubygems\ssl_certs` folder
-
-#### Permission issues during Ruby install
+Run the checks and development build:
-You could try a different method to install Ruby. Checkout
[rbenv](https://github.com/sstephenson/rbenv). Instructions:
+ npm test
+ npm run build
-1. Install rbenv
+To build the full site as the deployment workflows do, run:
- brew install rbenv ruby-build
+ npm run build:prod
-2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
-
- echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
-
-3. Install a version of `ruby` and set it to your local version:
+### Troubleshooting
- rbenv install 2.0.0-p647
- rbenv local 2.0.0-p647
+If `ruby --version` reports another version, check the order of Ruby
installations in `PATH` and open a new terminal after updating your shell
configuration.
+If gem installation fails with a compiler error, check that your platform's
development toolchain is installed. Use a Ruby installation writable by your
user to avoid needing administrator privileges for gem installation.
-[ruby_linux]:
https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
+[ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/
[homebrew]: https://brew.sh/
-[linux_node]:
https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
[ruby_downloads]: https://rubyinstaller.org/downloads/
-[ruby_installer]:
http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.2.3.exe
-[ruby_devkit]:
http://dl.bintray.com/oneclick/rubyinstaller/DevKit-mingw64-32-4.7.2-20130224-1151-sfx.exe
[nodejs]: https://nodejs.org/
-[python_downloads]: https://www.python.org/downloads/release/python-2711/
-[python_installer_mac]:
https://www.python.org/ftp/python/2.7.11/python-2.7.11-macosx10.6.pkg
-[python_installer_windows]:
https://www.python.org/ftp/python/2.7.11/python-2.7.11.amd64.msi
-[python_linux]: http://docs.python-guide.org/en/latest/starting/install/linux/
[cordova-docs]: https://github.com/apache/cordova-docs
-[GlobalSignRootCerficateAuthority]:
https://raw.githubusercontent.com/rubygems/rubygems/master/lib/rubygems/ssl_certs/index.rubygems.org/GlobalSignRootCA.pem
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
