Skip to content

Commit

Permalink
doc: update working on docs
Browse files Browse the repository at this point in the history
  • Loading branch information
erisu committed Oct 23, 2024
1 parent 8b847e8 commit c2ffdc7
Showing 1 changed file with 55 additions and 11 deletions.
66 changes: 55 additions & 11 deletions doc/working-on-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,68 @@
* 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:
Read more [here](https://github.com/apache/cordova-docs/blob/master/gulpfile.js#L212).

gulp newversion --version X.X.X
## Create new snapshot from `dev`

or manually run the `incrementversion.js` script:
The following commands can be used to create a new snapshot of `dev` docs:

node ./tools/bin/incrementversion.js www/docs X.X.X
```bash
npx gulp newversion
npx gulp newversion --bumpCli
```

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:
Please read the section, [Preparing Doc Release Scenarios](#Preparing-Doc-Release-Scenarios), below to understand which command fits your scenario.

gulp newversion --version X.X.X --language YY
## Preparing Doc Release Scenarios

or manually, to the script, as follows:
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.

node ./tools/bin/incrementversion.js www/docs X.X.X YY
Here are a few scenarios that will help decide how if we are updating an existing snapshot of creating a new one.

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

0 comments on commit c2ffdc7

Please sign in to comment.