This is an automated email from the ASF dual-hosted git repository. erisu pushed a commit to branch feat/versioning-and-htaccess in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
commit e7b2ada431d4cd71aca548c59489479dd3112fb7 Author: Erisu <[email protected]> AuthorDate: Fri Jan 9 12:38:27 2026 +0900 docs: update version info and build process to target latest --- .gitignore | 2 +- VERSION | 2 +- conf/_config.yml | 2 +- conf/_dev.yml | 4 +- gulpfile.js | 93 +++++++++-------------------------------------- tools/bin/fetch_docs.js | 2 +- tools/bin/gen_defaults.js | 4 +- tools/bin/gen_versions.js | 4 +- tools/bin/nextversion.js | 74 ------------------------------------- tools/bin/util.js | 4 +- www/_data/redirects.yml | 34 ----------------- www/_layouts/docs.html | 86 ------------------------------------------- 12 files changed, 29 insertions(+), 282 deletions(-) diff --git a/.gitignore b/.gitignore index d76a6beb0f..8faaa8cafa 100644 --- a/.gitignore +++ b/.gitignore @@ -14,7 +14,7 @@ www/static/css # done else where as these files are pulled from other sources # see fetch_docs.js for more details. # www/_data/fetched-files.yml contains an informative list of src/dest pairs -www/docs/*/dev/reference +www/docs/*/latest/reference/ node_modules ruby_modules diff --git a/VERSION b/VERSION index 3c4f918762..a0f9a4b4bc 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -13.x-2025.11 +latest diff --git a/conf/_config.yml b/conf/_config.yml index 09140a86e1..3349aa6874 100644 --- a/conf/_config.yml +++ b/conf/_config.yml @@ -19,7 +19,7 @@ excerpt_separator: <!--more--> # the version to which /latest/ points # NOTE: # this value gets overwritten in _version.yml, which is a generated file -latest_docs_version: dev +latest_docs_version: latest # the docs version that is shown by default when clicking on docs links on the site default_linked_docs_version: latest diff --git a/conf/_dev.yml b/conf/_dev.yml index 498682c45f..aa9dfd7406 100644 --- a/conf/_dev.yml +++ b/conf/_dev.yml @@ -1,5 +1,5 @@ baseurl: "" -default_linked_docs_version: dev +default_linked_docs_version: latest destination: build-dev exclude: @@ -7,4 +7,4 @@ exclude: - docs/ include: - - docs/en/dev + - docs/en/latest diff --git a/gulpfile.js b/gulpfile.js index 4cf99f69d6..503ecdda1f 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -17,8 +17,7 @@ const buffer = require('vinyl-buffer'); const htmllint = require('gulp-htmllint'); const Crawler = require('simplecrawler'); -const nextversion = require('./tools/bin/nextversion'); -const { listdirsSync, srcTocfileName, logger } = require('./tools/bin/util'); +const { listdirsSync, logger } = require('./tools/bin/util'); const HeaderTransform = require('./tools/HeaderTransform'); @@ -34,7 +33,7 @@ const PROD_DIR = path.join(ROOT_DIR, 'build-prod'); const DATA_DIR = path.join(SOURCE_DIR, '_data'); const TOC_DIR = path.join(DATA_DIR, 'toc'); const DOCS_DIR = path.join(SOURCE_DIR, 'docs'); -const FETCH_DIR = path.join(DOCS_DIR, 'en', 'dev', 'reference'); +const FETCH_DIR = path.join(DOCS_DIR, 'en', 'latest', 'reference'); const CSS_SRC_DIR = path.join(SOURCE_DIR, 'static', 'css-src'); const CSS_OUT_DIR = path.join(SOURCE_DIR, 'static', 'css'); const JS_DIR = path.join(SOURCE_DIR, 'static', 'js'); @@ -63,11 +62,8 @@ const BASE_URL = ''; const YAML_FRONT_MATTER = '---\n---\n'; const WATCH_INTERVAL = 1000; // in milliseconds const VERSION_VAR_NAME = 'latest_docs_version'; -const LATEST_DOCS_VERSION = fs.readFileSync(VERSION_FILE, 'utf-8').trim(); +const LATEST_DOCS_VERSION = 'latest'; -// '--bumpCli' flag hat determins if the next version is major CLI or new date release. -const bumpCli = argv.bumpCli || false; -const NEXT_DOCS_VERSION = nextversion.getNextVersion(bumpCli, LATEST_DOCS_VERSION); const LANGUAGES = listdirsSync(DOCS_DIR); const PROD_BY_DEFAULT = false; @@ -144,43 +140,6 @@ function jekyllBuild (done) { exec(bundle, ['exec', 'jekyll', 'build'].concat(flags), done); } -function copyDocsVersion (oldVersion, newVersion, cb) { - // copying a folder and a ToC file for each language - const numCopyOperations = LANGUAGES.length * 2; - - // pseudo-CV (condition variable) - let numCopied = 0; - function doneCopying (error) { - if (error) { - cb(error); - return; - } - - // call callback if all folders have finished copying - numCopied += 1; - if (numCopied === numCopyOperations) { - cb(); - } - } - - // create a new version for each language - LANGUAGES.forEach(function (languageName) { - // get files to copy - const oldVersionDocs = path.join(DOCS_DIR, languageName, oldVersion); - const oldVersionToc = path.join(TOC_DIR, srcTocfileName(languageName, oldVersion)); - const newVersionDocs = path.join(DOCS_DIR, languageName, newVersion); - const newVersionToc = path.join(TOC_DIR, srcTocfileName(languageName, newVersion)); - - // copy docs - console.log(oldVersionDocs + ' -> ' + newVersionDocs); - fs.cp(oldVersionDocs, newVersionDocs, { recursive: true, force: true }, doneCopying); - - // copy ToC - console.log(oldVersionToc + ' -> ' + newVersionToc); - fs.cp(oldVersionToc, newVersionToc, { recursive: true, force: true }, doneCopying); - }); -} - // tasks module.exports.help = module.exports.default = function help () { @@ -193,9 +152,8 @@ module.exports.help = module.exports.default = function help () { logger(' serve build the site and open it in a browser'); logger(' reload refresh the browser'); logger(''); - logger(' newversion create ' + NEXT_DOCS_VERSION + ' docs from dev docs'); - logger(' snapshot copy dev docs to ' + LATEST_DOCS_VERSION + ' docs'); - logger(''); + // logger(' snapshot creates an archive of latest docs'); + // logger(''); logger(' configs run all the below tasks'); logger(' defaults create ' + DEFAULTS_CONFIG_FILE); logger(' version create ' + VERSION_CONFIG_FILE); @@ -346,8 +304,8 @@ module.exports.watch = gulp.series(serve, function watch () { path.join(SOURCE_DIR, '_includes', '*.html'), path.join(SOURCE_DIR, '**', '*.html') + '!' + path.join(DOCS_DIR, '**'), path.join(SOURCE_DIR, '**', '*.md') + '!' + path.join(DOCS_DIR, '**'), - path.join(DOCS_DIR, 'en', 'dev', '**', '*.md'), - path.join(DOCS_DIR, 'en', 'dev', '**', '*.html') + path.join(DOCS_DIR, 'en', 'latest', '**', '*.md'), + path.join(DOCS_DIR, 'en', 'latest', '**', '*.html') ], { interval: WATCH_INTERVAL }, ['regen'] @@ -365,33 +323,16 @@ module.exports.lint = function lint () { .pipe(htmllint()); }; -module.exports.newversion = gulp.series(fetch, function newVersion (done) { - if (fs.existsSync(path.join(DOCS_DIR, 'en', NEXT_DOCS_VERSION))) { - logger(styleText(['red'], '[ERROR] ') + `The targeted docs version ""${NEXT_DOCS_VERSION}"" already exist. Are you trying to update the existing snapshot? Use "npm run update-docs".`); - process.exit(1); - } - - copyDocsVersion('dev', NEXT_DOCS_VERSION, function (error) { - if (error) { - console.error(error); - done(); - return; - } - - // finally update the version file with the new version - fs.writeFile(VERSION_FILE, NEXT_DOCS_VERSION + '\n', done); - }); -}); - -module.exports.snapshot = gulp.series(fetch, function snapshot (done) { - // remove current version first - LANGUAGES.forEach(function (languageName) { - const languageLatestDocs = path.join(DOCS_DIR, languageName, LATEST_DOCS_VERSION); - remove(languageLatestDocs); - }); - - copyDocsVersion('dev', LATEST_DOCS_VERSION, done); -}); +/** + * TODO: rewrite the snapshot to perform the following steps + * 1. create a temp directory + * 2. build docs into temp directory + * - A flag should be set so the build process know + * 1. dispaly this version is outdated & each page to try and link to its latest page. + * 2. the navbar to link to latest docs + */ +// module.exports.snapshot = gulp.series(fetch, function snapshot (done) { +// }); module.exports.checklinks = function checkLinks (done) { const crawler = new Crawler('http://localhost:3000/'); diff --git a/tools/bin/fetch_docs.js b/tools/bin/fetch_docs.js index 80f87bcd20..8d0b39a6bc 100644 --- a/tools/bin/fetch_docs.js +++ b/tools/bin/fetch_docs.js @@ -28,7 +28,7 @@ const util = require('./util'); // constants const DEFAULT_REPO_PATH = 'README.md'; -const DEFAULT_VERSION_NAME = 'dev'; +const DEFAULT_VERSION_NAME = 'latest'; const DEFAULT_LANGUAGE_NAME = 'en'; const THIS_FILE = path.basename(__filename); diff --git a/tools/bin/gen_defaults.js b/tools/bin/gen_defaults.js index 83eabfeef7..e676407dd4 100644 --- a/tools/bin/gen_defaults.js +++ b/tools/bin/gen_defaults.js @@ -24,7 +24,7 @@ const util = require('./util'); // constants const USAGE = 'Usage: gen_defaults.js [docsRoot] [latestVersion]'; -const DEV_VERSION_NAME = 'dev'; +const DEV_VERSION_NAME = 'latest'; // constants for sitemap.xml // reference: @@ -95,7 +95,7 @@ function main () { const versionDefaults = { scope: { - path: 'docs/' + langName + '/' + versionName + path: 'docs/en/latest' }, values: { version: versionName, diff --git a/tools/bin/gen_versions.js b/tools/bin/gen_versions.js index d5ac62d72f..f03b666181 100644 --- a/tools/bin/gen_versions.js +++ b/tools/bin/gen_versions.js @@ -43,7 +43,7 @@ function main () { // Get all directories, excluding dev, and make sure it is in lexicographically order. const versionNames = util.listdirsSync(langPath) - .filter(dir => dir !== 'dev') + .filter(dir => dir !== 'latest') .sort((a, b) => a.localeCompare(b)); // Semver cant sort invalid values. E.g. 10.x or 12.x-2025.01 @@ -59,7 +59,7 @@ function main () { .sort((a, b) => semver.compare(a.semantic, b.semantic)) .map(v => v.readable); - sortedVersions.push('dev'); // add back dev + sortedVersions.push('latest'); // add back dev // get language ID const langName = LANGUAGE_MAP[langId]; diff --git a/tools/bin/nextversion.js b/tools/bin/nextversion.js deleted file mode 100755 index aee09e3abe..0000000000 --- a/tools/bin/nextversion.js +++ /dev/null @@ -1,74 +0,0 @@ -// Licensed to the Apache Software Foundation (ASF) under one -// or more contributor license agreements. See the NOTICE file -// distributed with this work for additional information -// regarding copyright ownership. The ASF licenses this file -// to you under the Apache License, Version 2.0 (the -// "License"); you may not use this file except in compliance -// with the License. You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. - -'use strict'; - -function getNextVersion (bumpCli, previousVersion) { - bumpCli = bumpCli || false; - - // get previous version number - // NOTE: - // only versions of the form N.x are accepted - const previousVersionMatch = previousVersion.match(/^(\d+)\.x(-\d{4}.\d{2})?$/); - if (!previousVersionMatch) { - throw Error('invalid version'); - } - - // get next major version - const previousMajor = previousVersionMatch[1]; - const nextMajor = bumpCli - ? parseInt(previousMajor) + 1 - : parseInt(previousMajor); - - // create next version - const currentDate = new Date(); - const currentYear = currentDate.getFullYear(); - const currentMonth = (currentDate.getMonth() + 1).toString().padStart(2, '0'); - const nextVersion = `${nextMajor}.x-${currentYear}.${currentMonth}`; - - return nextVersion; -} - -function main () { - // get arg - const shouldBumpCli = process.argv[2] || false; - const previousVersion = process.argv[3]; - - if (!previousVersion) { - console.error('no version specified'); - process.exit(1); - } - - // try to get the next version - let nextVersion = null; - try { - nextVersion = getNextVersion(shouldBumpCli, previousVersion); - } catch (e) { - console.error(e); - process.exit(1); - } - - console.log(nextVersion); -} - -module.exports = { - getNextVersion -}; - -if (require.main === module) { - main(); -} diff --git a/tools/bin/util.js b/tools/bin/util.js index 5293cda89e..6cf1fb638d 100644 --- a/tools/bin/util.js +++ b/tools/bin/util.js @@ -81,11 +81,11 @@ module.exports = (function () { } function srcTocfileName (language, version) { - return tocfileName(language, version, 'src'); + return tocfileName('en', 'latest', 'src'); } function genTocfileName (language, version) { - return tocfileName(language, version, 'gen'); + return tocfileName('en', 'latest', 'gen'); } function mergeObjects (a, b) { diff --git a/www/_data/redirects.yml b/www/_data/redirects.yml index 1146a343e3..f07055caf5 100644 --- a/www/_data/redirects.yml +++ b/www/_data/redirects.yml @@ -3,7 +3,6 @@ # 302 (temporary) renames of versions version-renames: - "edge": "dev" "6.0.0": "6.x" # 302 (temporary) renames of languages @@ -16,68 +15,35 @@ general: # 301 (PERMANENT) redirect paths relative to /docs/XX/ docs: - "dev/guide/platforms/android/tools.html": "dev/guide/platforms/android/index.html" "latest/guide/platforms/android/tools.html": "latest/guide/platforms/android/index.html" - - "dev/guide/platforms/android/lifecycle.html": "dev/guide/platforms/android/index.html#lifecycle-guide" "latest/guide/platforms/android/lifecycle.html": "latest/guide/platforms/android/index.html#lifecycle-guide" - - "dev/guide/platforms/android/config.html": "dev/config_ref/index.html" "latest/guide/platforms/android/config.html": "latest/config_ref/index.html" - - "dev/guide/platforms/ios/tools.html": "dev/guide/platforms/ios/index.html" "latest/guide/platforms/ios/tools.html": "latest/guide/platforms/ios/index.html" - - "dev/guide/platforms/ios/config.html": "dev/config_ref/index.html" "latest/guide/platforms/ios/config.html": "latest/config_ref/index.html" - - "dev/guide/platforms/win8/packaging.html": "dev/guide/platforms/win8/index.html#signing-an-app" "latest/guide/platforms/win8/packaging.html": "latest/guide/platforms/win8/index.html#signing-an-app" - - "dev/guide/platforms/win8/win10-support.html": "dev/guide/platforms/win8/index.html" "latest/guide/platforms/win8/win10-support.html": "latest/guide/platforms/win8/index.html" - - "dev/cordova/plugins/pluginapis.html": "deprecated.html" "latest/cordova/plugins/pluginapis.html": "deprecated.html" # Rename `cordova-windows` URLs from `win8` to `windows` - "dev/guide/platforms/win8/index.html": "dev/guide/platforms/windows/index.html" "latest/guide/platforms/win8/index.html": "latest/guide/platforms/windows/index.html" - "dev/guide/platforms/win8/plugin.html": "dev/guide/platforms/windows/index.html" "latest/guide/platforms/win8/plugin.html": "latest/guide/platforms/windows/index.html" - "dev/guide/platforms/win8/upgrade.html": "dev/guide/platforms/windows/index.html" "latest/guide/platforms/win8/upgrade.html": "latest/guide/platforms/windows/index.html" # Removing deprecated platforms and plugins - "dev/guide/platforms/blackberry10/home.html": "deprecated.html" "latest/guide/platforms/blackberry10/home.html": "deprecated.html" - "dev/guide/platforms/blackberry10/index.html": "deprecated.html" "latest/guide/platforms/blackberry10/index.html": "deprecated.html" - "dev/guide/platforms/blackberry10/tools.html": "deprecated.html" "latest/guide/platforms/blackberry10/tools.html": "deprecated.html" - "dev/guide/platforms/blackberry10/config.html": "deprecated.html" "latest/guide/platforms/blackberry10/config.html": "deprecated.html" - "dev/guide/platforms/blackberry10/plugin.html": "deprecated.html" "latest/guide/platforms/blackberry10/plugin.html": "deprecated.html" - "dev/guide/platforms/blackberry10/upgrade.html": "deprecated.html" "latest/guide/platforms/blackberry10/upgrade.html": "deprecated.html" - "dev/guide/platforms/blackberry/upgrade.html": "deprecated.html" "latest/guide/platforms/blackberry/upgrade.html": "deprecated.html" - "dev/guide/platforms/ubuntu/index.html": "deprecated.html" "latest/guide/platforms/ubuntu/index.html": "deprecated.html" - "dev/guide/platforms/wp8/home.html": "deprecated.html" "latest/guide/platforms/wp8/home.html": "deprecated.html" - "dev/guide/platforms/wp8/index.html": "deprecated.html" "latest/guide/platforms/wp8/index.html": "deprecated.html" - "dev/guide/platforms/wp8/plugin.html": "deprecated.html" "latest/guide/platforms/wp8/plugin.html": "deprecated.html" - "dev/guide/platforms/wp8/upgrade.html": "deprecated.html" "latest/guide/platforms/wp8/upgrade.html": "deprecated.html" - "dev/guide/platforms/wp8/parallels.html": "deprecated.html" "latest/guide/platforms/wp8/parallels.html": "deprecated.html" - "dev/guide/platforms/wp8/vmware.html": "deprecated.html" "latest/guide/platforms/wp8/vmware.html": "deprecated.html" - "dev/guide/platforms/wp8/webview.html": "deprecated.html" "latest/guide/platforms/wp8/webview.html": "deprecated.html" "latest/reference/cordova-plugin-contacts/index.html": "deprecated.html" diff --git a/www/_layouts/docs.html b/www/_layouts/docs.html index 87617dafe8..8fb4f39c5c 100644 --- a/www/_layouts/docs.html +++ b/www/_layouts/docs.html @@ -114,65 +114,6 @@ NOTE: <a class="edit" href="{{ edit_link }}"><span class="glyphicon glyphicon-pencil" aria-hidden="true"></span> {{ page.edit_source_text }}</a> {% endif %} {% endif %} - - <!-- Version dropdown --> - <div class="dropdown"> - <button class="btn btn-default dropdown-toggle" type="button" id="versionDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true"> - {{ page.version }} - {% if page.version == site.latest_docs_version %} - ({{ layout.latest_text }}) - {% endif %} - <span class="caret"></span> - </button> - <ul class="dropdown-menu" aria-labelledby="versionDropdown"> - - <!-- List versions available in this language --> - {% for other_version in site.data.docs-versions[page.language].versions reversed %} - <li> - {% comment %} - Name the latest version as "latest" to take advantage of redirects for "/latest/". - {% endcomment %} - {% if other_version == site.latest_docs_version %} - {% assign other_version_string = "latest" %} - {% else %} - {% assign other_version_string = other_version %} - {% endif %} - - {% capture version_entry_string %} - {{ other_version }} - {% if other_version == site.latest_docs_version %} - ({{ layout.latest_text }}) - {% endif %} - {% endcapture %} - - {% comment %} - Replace only the version part of the URI, thereby redirecting to - the same page in the other version. - - NOTE: - This page might not exist in the target version because page - layouts change from version to version - {% endcomment %} - {% capture other_version_root %}/docs/{{ page.language }}/{{ other_version_string }}/{% endcapture %} - {% assign other_version_url = page_url | replace:VERSION_ROOT,other_version_root %} - - {% unless ALL_PAGES contains other_version_url %} - {% assign other_version_url = other_version_root %} - {% endunless %} - - <a href="{{ site.baseurl }}{{ other_version_url }}" class="{% unless ALL_PAGES contains other_version_url %}missing-page{% endunless %}"> - {% if page.version == other_version %} - <span class="selected"> - {{ version_entry_string }} - </span> - {% else %} - {{ version_entry_string }} - {% endif %} - </a> - </li> - {% endfor %} - </ul> - </div> </div> {% comment %} @@ -188,33 +129,6 @@ NOTE: {% assign latest_url = latest_root %} {% endunless %} - <!-- Show warnings for special versions --> - <!-- dev warning --> - {% if page.version == 'dev' %} - <div class="alert docs-alert alert-info" role="alert"> - <button type="button" class="close" data-dismiss="alert" aria-label="Close"> - <span aria-hidden="true">×</span> - </button> - {{ layout.in_development_text }} - <a href="{{ site.baseurl }}{{ latest_url }}"> - {{ layout.click_here_text }} - </a> - </div> - {% endif %} - - <!-- outdated warning --> - {% if page.version != 'dev' and page.version != site.latest_docs_version %} - <div class="alert docs-alert alert-danger" role="alert"> - <button type="button" class="close" data-dismiss="alert" aria-label="Close"> - <span aria-hidden="true">×</span> - </button> - {{ layout.outdated_text }} - <a href="{{ site.baseurl }}{{ latest_url }}"> - {{ layout.click_here_text }} - </a> - </div> - {% endif %} - <!-- plugin version warning --> {% if page.plugin_name and page.plugin_version %} <div class="alert alert-warning docs-alert" role="alert"> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
