Developer documentation

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: lerna bootstrap.

  • 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 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 ./fake_resources_rollup.js before && npx rollup --config --en_US && node ./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

  • update target version in antora.yml

  • update ROSAENLG_VERSION in .gitlab-ci.yml

  • 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: npm run deploy:dev * then deploy on prod: npm run deploy:prod * check on prod