Developer documentation

This is the documentation for 1.17.0 version, which is not the latest version. Consider upgrading to 3.4.0.

Read this if you want to contribute to RosaeNLG. Alternatively, as the author, this is my own personal doc when I forget how things work.

The repo

On Gitlab:

It is a multi package repo (lerna) which is a fork of Pug @2.0.3 (forked the 06/04/2018). 03/06/2019, @2.0.3 is still the official released version of Pug. 29/09/2019 @2.0.4 has been publshed.

  • rosaenlg is the main package. Derived from pug.

  • rosaenlg-pug-xxx are forks of the original pug-xxx packages:

    • Some of them are are unchanged, but I needed to fork them because they carry dependencies with changed packages: rosaenlg-pug-filters rosaenlg-pug-linker rosaenlg-pug-load

    • Some of them are changed to handle specific structures like synz > syn: rosaenlg-pug-lexer rosaenlg-pug-parser rosaenlg-pug-walk pug-code-gen

  • rosaenlg-yseop is an Yseop template generator for RosaeNLG templates, derived from rosaenlg-pug-code-gen (itself a fork of pug-code-gen).

  • and multiple packages that each contain a set of features

Pre install

  • lerna: npm install lerna -g

  • yarn: npm install yarn -g

  • mocha: npm install mocha -g

Install

  • Linking: yarn install.

  • Build the linguistic resources and the typescript files: lerna run build.

  • Run the tests:

    • lerna run test

    • I also use npm test directly in packages/rosaenlg folder

    • and also mocha test-rosaenlg/unit.js _lang_fr_FR etc. to run a specific test

Linking a RosaeNLG project with the local copy of the repo

In your project: do not run npm install as it will download each RosaeNLG package. And do not use npm link.

  • just install the other dependencies: for instance npm install junit

  • make a symbolic link in your project to your local copy of RosaeNLG: mklink /D node_modules\rosaenlg c:\rosaenlg\rosaenlg\packages\rosaenlg

Creating a new linguistic resource

this should be more clear and detailed

  • create the module:

    • create a distinct module that only contains a JSON file with the linguistic resource e.g. french-verbs-lefff

    • create a module that exploits that JSON file, but only with devDependencies on the linguistic resource: in order to test properly, but not to link them together e.g. french-verbs

  • use it in RosaeNLG:

    • use both modules in rosaenlg main module, declaring them as dependencies

    • add them in fake_resources_before.sh and fake_resources_after.sh so that tsc does not become too slow

    • make it work, adapt VerbsManager.ts or whatever etc.; use build:tsc to build

    • run tests in unit.js - they should work

  • adapt module rosaenlg-pug-code-gen

    • enrich helper.ts

    • add test cases

    • most of the time you should not have to modify index.js (which is a good news)

  • browser packaging:

    • add in ../_helpers/fake_resources_rollup.js to accelerate rollup browser packaging

    • declare them properly in rollup.config.js: the linguistic resource must not be included in the standard package, but only in the package to compile templates (the big one)

    • enrich tiny.js

    • run something like node ../_helpers/fake_resources_rollup.js before && npx rollup --config --en_US && node ../_helpers/fake_resources_rollup.js after (change language)

    • check manually the content of each bundled package

    • mocha on tiny.js should work

Publishing a new version

this doc is just for me

RosaeNLG packages:

  • check non regression on another project

  • check changelog.adoc content, but leave == [Unreleased]

  • run release.js with patch / minor / major as only param; this must update changelog.adoc, antora.yml and .gitlab-ci.yml

  • commit on the branch

  • merge with master

  • local environment: lerna version --no-push --no-git-tag-version --exact patch (or minor etc. instead of patch)

  • commit

  • make a vXX.XX.XX branch (to be seen by the doc project + to publish)

  • push: git push origin master

  • also push branch: git push origin vXX.XX.XX

  • Gitlab CI should build and should publish on npm

Documentation: * trigger the antora-ui project CI on gitlab * trigger the docs-site project CI on gitlab and check the result * trigger the antora-playbook CI on gitlab ** and trigger manually the publication

Misc:

  • remove old branches on Gitlab

  • update the boilerplate

Update sibling project rosaenlg-java.

Publish new API on Lambda: * first test on dev: yarn run deploy:dev * migrate existing templates using server-scripts if they are not compatible * then deploy on prod: yarn run deploy:prod * check on prod