diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5079825bce5..a5b9fc80692 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 5d17d333004..168b5b33674 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 03a09dfd10e..f2feb7a2714 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 8d512815c3e..0ac82b7ed0c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,7 @@ -[![Build Status](https://travis-ci.org/apache/cordova-docs.svg?branch=master)](https://travis-ci.org/apache/cordova-docs) +[![Build Test](https://github.com/apache/cordova-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/apache/cordova-docs/actions/workflows/ci.yml) +[![Deploy Staging Site](https://github.com/apache/cordova-docs/actions/workflows/deploy-stage.yml/badge.svg)](https://github.com/apache/cordova-docs/actions/workflows/deploy-stage.yml) +[![Deploy Prod Site](https://github.com/apache/cordova-docs/actions/workflows/deploy-prod.yml/badge.svg)](https://github.com/apache/cordova-docs/actions/workflows/deploy-prod.yml) +[![Release Auditing](https://github.com/apache/cordova-docs/actions/workflows/release-audit.yml/badge.svg)](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 d815ea12693..47a7a596519 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 923185ad57f..63499105da1 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 174cbe89859..418373c41b4 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 ruby@3.4 - brew install ruby@2.0 +Add its executables to your shell's `PATH` before any other Ruby installation: -#### Node.js + export PATH="$(brew --prefix ruby@3.4)/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