doc: update version pattern <cli version>-<year>.<month> (#1368)

* feat: update version pattern <cli version>-<year>.<month>
* feat: update newversion - require flag --bumpCli to bump major
* doc: update working on docs
* doc: remove random read more link
* doc: check targeted version in newversion task

Author: erisu

doc/working-on-docs.md

@@ -7,24 +7,66 @@
 * This can also be executed via `gulpfile.js` task `fetch`, by running `gulp fetch` which pulls in the files to `dev/en/{file dest}`.
 * Most auto-generated files have a comment tag at the top of the file to indicate that they come from elsewhere.
 
-## Update latest (x.y) from `dev`
+## Update current docs from `dev`
 
-Normal build doesn't update latest (7.x) from dev version of docs. You will need to do this manually using `gulp snapshot`. Read more [here](https://github.com/apache/cordova-docs/blob/master/gulpfile.js#L212).
+The following command can quickly sync the `dev` docs with the current latest docs:
 
-## Create new version of the docs
+```bash
+npm run update-docs
+```
 
-To increment the documentation version (e.g. `X.X.X`, either use the gulp task:
+## Create new snapshot from `dev`
 
-    gulp newversion --version X.X.X
+The following commands can be used to create a new snapshot of `dev` docs:
 
-or manually run the `incrementversion.js` script:
+```bash
+npx gulp newversion
+npx gulp newversion --bumpCli
+```
 
-    node ./tools/bin/incrementversion.js www/docs X.X.X
+Please read the section, [Preparing Doc Release Scenarios](#Preparing-Doc-Release-Scenarios), below to understand which command fits your scenario.
 
-To only run for a specific language (__this should only happen when translation is intentionally left out for a given version__), specify the language to the Gulp task as follows:
+## Preparing Doc Release Scenarios
 
-    gulp newversion --version X.X.X --language YY
+When preparing to release docs, there are two things to be aware of, the version of Cordova CLI and if the changes warrants for a new doc version.
 
-or manually, to the script, as follows:
+Here are a few scenarios that will help decide how if we are updating an existing snapshot of creating a new one.
 
-    node ./tools/bin/incrementversion.js www/docs X.X.X YY
+1. Are we preparing to release new docs because there was a major release of Cordova CLI?
+
+    If the answer is **yes**, then we will be creating a new version of docs with the following command:
+
+    ```bash
+    npx gulp newversion --bumpCli
+    ```
+
+    If the current released docs version is `12.x` and we are preparing for Cordova-CLI 13.x, the above command will create `13.x-2024.10`.
+
+    > Notice: The year and month will be appended automatically.
+
+2. Are we preparing to release new docs because there was a minor or patch release of Cordova CLI?
+
+    If the answer is **yes**, then we do not need to make a new snapshot. In this case, we can update an existing snapshot with the following command:
+
+    ```bash
+    npm run update-docs
+    ```
+
+    > Notice: In this scenario we are expecting the version to already exist. If it was missing, then we would have to create a new snapshot but in most cases it should never be missing.
+
+3. Are we preparing docs for a major release to one or more of Cordova's platforms while the CLI version was unchanged?
+
+    If the answer is **yes**, then we need to make a new snapshot, but we do not need to bump the CLI major. We can do this with the following command:
+
+    ```bash
+    npx gulp newversion
+    ```
+
+    If the current doc snapshot is `12.x`, then the above command will create a new snapshot with the same CLI major version but the appended date will be different.
+
+    E.g. `12.x-2024.10`
+
+    > Notice:
+    >
+    > *`12.x` and older does not have date appended. Any newly created snapshots will append the date value.
+    > * If we already have `12.x-2024.10` and the month is still the same, we should use senario 2. `npm run update-docs`.

gulpfile.js

@@ -67,9 +67,11 @@ 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 NEXT_DOCS_VERSION = nextversion.getNextVersion(LATEST_DOCS_VERSION);
-const LANGUAGES = listdirsSync(DOCS_DIR);
 
+// '--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;
 
 // compute/get/set/adjust passed options
@@ -381,6 +383,11 @@ module.exports.lint = function lint () {
 };
 
 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);

tools/bin/nextversion.js

@@ -17,28 +17,37 @@
 
 'use strict';
 
-function getNextVersion (previousVersion) {
+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$/);
+    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 = parseInt(previousMajor) + 1;
+    const nextMajor = bumpCli
+        ? parseInt(previousMajor) + 1
+        : parseInt(previousMajor);
 
     // create next version
-    const nextVersion = nextMajor + '.x';
+    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 previousVersion = process.argv[2];
+    const shouldBumpCli = process.argv[2] || false;
+    const previousVersion = process.argv[3];
+
     if (!previousVersion) {
         console.error('no version specified');
         process.exit(1);
@@ -47,7 +56,7 @@ function main () {
     // try to get the next version
     let nextVersion = null;
     try {
-        nextVersion = getNextVersion(previousVersion);
+        nextVersion = getNextVersion(shouldBumpCli, previousVersion);
     } catch (e) {
         console.error(e);
         process.exit(1);