diff --git a/docs/docs/assets/stylesheets/extra.css b/docs/docs/assets/stylesheets/extra.css index d347e118c7..5bcf875334 100644 --- a/docs/docs/assets/stylesheets/extra.css +++ b/docs/docs/assets/stylesheets/extra.css @@ -102,3 +102,8 @@ .md-typeset figure img { display: unset; } + +/* Black banner */ +.md-banner { + background-color: black; +} \ No newline at end of file diff --git a/docs/docs/code-of-conduct.md b/docs/docs/contributing/code-of-conduct.md similarity index 93% rename from docs/docs/code-of-conduct.md rename to docs/docs/contributing/code-of-conduct.md index 6f92fe3fb2..d57cca7e35 100644 --- a/docs/docs/code-of-conduct.md +++ b/docs/docs/contributing/code-of-conduct.md @@ -120,7 +120,7 @@ the community. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html). Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). @@ -128,5 +128,5 @@ enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. \ No newline at end of file +[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are available at +[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). \ No newline at end of file diff --git a/docs/docs/contributing/development.md b/docs/docs/contributing/development.md new file mode 100644 index 0000000000..ce1b6c9b49 --- /dev/null +++ b/docs/docs/contributing/development.md @@ -0,0 +1,165 @@ +# Development + +Contributions are very much welcome. +But please follow the following guidelines and our [Code of Conduct](code-of-conduct.md){target=_blank}. + +## GitHub Flow + +Our branching workflow follows [GitHub Flow](https://docs.github.com/de/get-started/quickstart/github-flow){target=_blank}. + +## Branch Naming Convention + +Branches should be names as follows + +- `fix-short-title` for bug fixes +- `docs-short-title` for documentations +- `feature-short-title` for features +- `refactor-short-title` for refactoring +- `imrpove-short-title` for improvements +- `project-short-title` for thesis, EnPro, StuPro ... + +## Squash and Merge + +Please squash your commits into a single commit with a short but meaningful message and delete the branch afterwards. +The commit message should not have a link to the merge request. + + +## Command Line Interface + +!!! Info + `yarn cli` uses `src/cli/index.ts` while `yarn vintner` uses `build/cli/index.js`. + Therefore, run `yarn cli` to execute the current code without building it first. + +The CLI is build using [commander.js](https://github.com/tj/commander.js){target=_blank}. +The entry point is `src/cli/index.ts`. +To execute a CLI command during development, run + +```shell linenums="1" +yarn cli [command] [options] +``` + +## Server + +The server is build using [express](https://github.com/expressjs/express){target=_blank}. +The entry point is `src/server/index.ts`. +To run a development server on [http://localhost:3000](http://localhost:3000){target=_blank} with live-reload, run + +```shell linenums="1" +yarn server:serve +``` + +## Tests + +We use [mocha](https://mochajs.org){target=_blank}, [chai](https://www.chaijs.com){target=_blank}, and [nyc](https://istanbul.js.org){target=_blank} for testing. +Respective tests are inside the `tests` directory. +To run the tests, use + +```shell linenums="1" +yarn test +``` + +To run the tests inside docker, use + +```shell linenums="1" +yarn test:docker +``` + +On pushes to the `main` branch these tests are executed. + +## Lint + +[ESLint](https://eslint.org){target=_blank} is used for linting. +To lint typescript, run the following command + +```shell linenums="1" +yarn lint:check +``` + +To fix lint problems, run the following command + +```shell linenums="1" +yarn lint:fix +``` + +## Code Style + +[Prettier](https://prettier.io){target=_blank} is used to format code. +To check the code style, run the following command + +```shell linenums="1" +yarn style:check +``` + +To fix code style problems, run the following command + +```shell linenums="1" +yarn style:fix +``` + +## Benchmark + +Run the following command, to run to benchmark the variability resolving. + +```shell linenums="1" +yarn benchmark +``` + +## Licenses + +[license-checker](https://github.com/davglass/license-checker){target=_blank} is used for handling licenses of (transitive) dependencies. +To check that (transitive) dependencies are licensed as expected, run the following command. +This check is also executed inside workflows. + +```shell linenums="1" +yarn licenses:check +``` + + +## Patch Packages + +We use [`patch-package`](https://github.com/ds300/patch-package){target=_blank} to fixing third party libraries. +For example, adding `logic-solver.d.ts` to [`logic-solver`](https://github.com/meteor/logic-solver){target=_blank}. +Therefore, make changes to the package inside `node_modules`, then run the following command. + +```shell linenums="1" +yarn patch-package ${package-name} +``` + +If you need to patch the `package.json`, then append the option `--exclude 'nothing'` as stated in [#311](https://github.com/ds300/patch-package/issues/311){target=_blank}. + +## Build + +To locally build the project, run the following command. +This will transpile Javascript inside the `/build` directory. + +```shell linenums="1" +yarn build +``` + +## Package + +{{ linux_only_notice() }} + +To locally package the project, run the following command. +This will package the previously transpiled Javascript using [`pkg`](https://github.com/vercel/pkg){target=_blank} and +generate binaries inside the `/dist` directory. + +```shell linenums="1" +yarn package +``` + +The issue considering the failed bytecode generation of MiniSat is known and can be ignored in our case. + +## Release + +On pushes to the `main` branch, the `release` workflow is triggered. +This workflow runs several tests, builds and packages the project and creates a new release. +Thereby, an existing release and `latest` tag is deleted. +There is only one release at total. +During the workflow the string `__VERSION__` inside a Javascript file is replace with the current commit hash. +The current version can be checked using `vintner --version`. + +## Night + +The `night` workflow is scheduled for every tuesday at 420. +This workflow ensures that the latest release is correctly signed and can be executed. \ No newline at end of file diff --git a/docs/docs/contributing/documentation.md b/docs/docs/contributing/documentation.md new file mode 100644 index 0000000000..b16a6e3e66 --- /dev/null +++ b/docs/docs/contributing/documentation.md @@ -0,0 +1,211 @@ +# Documentation + +This document gives an introduction on writing the documentation. + +## MkDocs + +{{ linux_only_notice() }} + +The documentation is powered by [Material for MkDocs](https://squidfunk.github.io/mkdocs-material){target=_blank}. +Corresponding files are located in the `docs` directory. +Custom macros are implemented in `docs/macros.py` using [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io){target=_blank}. + +We expect that Python and [pandoc](https://pandoc.org){target=_blank} is already installed. +To install [pandoc](https://pandoc.org){target=_blank} on Ubuntu you might run + +```shell linenums="1" +sudo apt-get install pandoc +``` + +With the following command you can install `mkdocs-material` along with its requirements globally on your system. + +```shell linenums="1" +yarn docs:install +``` + +To start a local development server on [http://localhost:8000](http://localhost:8000){target=_blank}, run the following command. + +```shell linenums="1" +yarn docs:serve +``` + +Once the server is running, run the following command to open the docs in your browser. + +```shell linenums="1" +yarn docs:open +``` + +## Autogenerated Markdown + +Some Markdown files are autogenerated, e.g., [Dependencies](../dependencies.md){target=_blank} or [Interface](../interface.md){target=_blank}. +Changes must be made in the respective template files. +Furthermore, respective files are generated during the `release` workflow and, therefore, overwrite respective files. +To warn the developer, include the following custom marco at the top of the template. + +```text linenums="1" +{% raw %} +{{ autogenerated_notice('yarn docs:generate:licenses') }} +{% endraw %} +``` + +This will render the following warning, if the docs are served using `yarn docs:serve` but not when built. + +{{ autogenerated_notice('yarn docs:generate:licenses', True) }} + + +## Casts + +{{ linux_only_notice() }} + +The docs contain recorded demos. Thereby, we use the following tools + +- [asciinema](https://asciinema.org/){target=_blank} to record a terminal session +- [demo-magic](https://github.com/paxtonhare/demo-magic){target=_blank} to automate the terminal session +- [asciinema-player](https://github.com/asciinema/asciinema-player){target=_blank} embed casts in a standalone manner + +Casts are not recorded during any workflow. +The following command can be used to record the `home` cast for the landing page + +```shell linenums="1" +yarn docs:record:home +``` + +A cast can be embedded using the custom macro `asciinema_player` as follows inside a Markdown file. + +```text linenums="1" +{% raw %} +{{ asciinema_player('getting-started') }} +{% endraw %} +``` + +This will embed the cast `docs/docs/assets/casts/getting-started.cast` inside the page as follows. + +{{ asciinema_player('getting-started') }} + + +## Export + +{{ linux_only_notice() }} + +To export registered pages as PDF, run the following command. +This will output the results in `dist-docs`. + +```shell linenums="1" +yarn docs:export +``` + +The above command is using [https://vintner.opentosca.org](https://vintner.opentosca.org){target=_blank}. +To export pages of [http://localhost:8000](http://localhost:8000){target=_blank}, run the following command. + +```shell linenums="1" +yarn docs:export:local +``` + + +## Interface + +To generate the documentation for the CLI and REST API, run the following command. +This command is also executed during the `release` workflow and, therefore, overwrites respective files. + +```shell linenums="1" +yarn docs:generate:interface +``` + +## Licenses + +To generate a list of licenses for all (transitive) dependencies, run the following command +This command is also executed during the `release` workflow and, therefore, overwrites respective files. + +```shell linenums="1" +yarn docs:generate:licenses +``` + +The list includes information such as package name, version, license, etc. and is written to a CSV file. +At the same time, the [Dependencies](../dependencies.md){target=_blank} page is generated. + +## Puccini + +{{ linux_only_notice() }} + +We use [puccini](https://github.com/tliron/puccini) to validate a service template. +Therefore, run the following command. + +```shell linenums="1" +yarn puccini:check:single path/to/service-template.yaml +``` + +To validate all registered service templates, run the following command. + +```shell linenums="1" +yarn puccini:check +``` + +## PlantUML + +We use [PlantUML](http://plantuml.com) for visualizing UML diagrams. +Read [PlantUML Guide](https://plantuml.com/de/guide) for modeling instructions. + +The following command generates PlantUML files for registered service templates. +This command is also executed during the `release` workflow and, therefore, overwrites respective files. +Furthermore, [mkdocs_build_plantuml](https://github.com/quantorconsulting/mkdocs_build_plantuml){target=_blank} is used to plot PlantUML to SVGs when building the documentation. + +```shell linenums="1" +yarn docs:generate:puml +``` + +Note, we use the public PlantUML server [https://www.plantuml.com/plantuml](https://www.plantuml.com/plantuml){target=_blank} for plotting SVGs. +It is also possible to start a local PlantUML server using Docker. +Therefore, run the following command. + +```shell linenums="1" +yarn puml:up +``` + +However, you also need to configure the following environment variables in `docs/.env`. + +```yaml linenums="1" +MKDOCS_PUML_SERVER=http://localhost:8080 +MKDOCS_PUML_SERVER_SSL=true +``` + +To stop the local PlantUML server, run the following command. + +```shell linenums="1" +yarn puml:down +``` + +There is also a deprecated way to plot PlantUML to SVG. +Therefore, run the following command. +This considers all `.puml` files. + +```shell linenums="1" +yarn docs:plot:puml +``` + +## Queries4TOSCA + +To generate the conformance tests for Queries4TOSCA, run the following command. +This command is also executed during the `release` workflow and, therefore, overwrites respective files. + +```shell linenums="1" +yarn docs:generate:tests:query +``` + +## TOSCA SofDCar Profile + +To generate the TOSCA SofDCar Profile, run the following command. +This command is also executed during the `release` workflow and, therefore, overwrites respective files. + +```shell linenums="1" +yarn docs:generate:tests:query +``` + + +## Variability4TOSCA + +To generate the conformance tests for Variability4TOSCA, run the following command. +This command is also executed during the `release` workflow and, therefore, overwrites respective files. + +```shell linenums="1" +yarn docs:generate:tests:query +``` diff --git a/docs/docs/development/intellij-eslint.png b/docs/docs/contributing/intellij-eslint.png similarity index 100% rename from docs/docs/development/intellij-eslint.png rename to docs/docs/contributing/intellij-eslint.png diff --git a/docs/docs/development/intellij-prettier.png b/docs/docs/contributing/intellij-prettier.png similarity index 100% rename from docs/docs/development/intellij-prettier.png rename to docs/docs/contributing/intellij-prettier.png diff --git a/docs/docs/notes.md b/docs/docs/contributing/notes.md similarity index 100% rename from docs/docs/notes.md rename to docs/docs/contributing/notes.md diff --git a/docs/docs/contributing/setup.md b/docs/docs/contributing/setup.md new file mode 100644 index 0000000000..f5f9f67807 --- /dev/null +++ b/docs/docs/contributing/setup.md @@ -0,0 +1,91 @@ +# Setup + +We use the following setup as working environment during development. + +## Node.js + +We are using [Node.js](https://nodejs.org){target=_blank} version `16.14.0`. +To install node, use [nvm](https://github.com/nvm-sh/nvm){target=_blank} or [nvm-windows](https://github.com/coreybutler/nvm-windows){target=_blank}. + +```shell linenums="1" +nvm install v16.14.0 +nvm use 16.14.0 +``` + +## Yarn + +We are using [Yarn 1 (Classic)](https://classic.yarnpkg.com/lang/en){target=_blank}. +Install it as follows. + +```shell linenums="1" +npm install --global yarn +``` + +## Repository + +The repository is a monorepo consisting of the CLI, server, docs and tests. +Clone it as follows. + +```shell linenums="1" +git clone https://github.com/opentosca/opentosca-vintner.git +cd opentosca-vintner +git lfs install +git lfs pull +yarn --frozen-lockfile +``` + +## Large Files + +Larges files, such as binaries or archives used in examples, are added using [git lfs](https://git-lfs.com){target=_blank}. +This includes the following file extensions `.bin`, `.gz`, `.tar`, `.zip`, `.xz`, and `.jar`. + +## Signed Commits + +Commits are required to be signed. +Therefore, you need to register a signing key. +For more information see + +- [Generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key){target=_blank} +- [Adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account){target=_blank} +- [Telling Git About Your Signing Key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key){target=_blank} +- [Signing Commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits){target=_blank} + +You can enable auto-signing for a specific repository with the following command + +```shell linenums="1" +git config commit.gpgsign true +``` + +## JetBrains + +!!! Warning + WebStorm Version 2022.3.3 seems to have problems with breakpoints when `src/resolver/graph.ts` is involved. + However, WebStorm Version 2022.3.2 works fine. + +We recommend to use [IntelliJ IDEA](https://www.jetbrains.com/idea){target=_blank} +or [WebStorm](https://www.jetbrains.com/webstorm){target=_blank} installed +using [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app){target=_blank}. +Both are [for free](https://www.jetbrains.com/community/education/#students){target=_blank} for students. +Open the Project Settings using `Ctrl + Alt + S` to configure ESLint and Prettier. + +ESLint should be configured as given in the figure below with the following pattern. + +```text linenums="1" +{**/*,*}.{ts} +``` + +
+ ![IntelliJ ESLint Settings](intellij-eslint.png){class=figure} +
Figure 1: IntelliJ ESLint Settings
+
+ +Prettier should be configured as given in the figure below with the following pattern. + +```text linenums="1" +{**/*,*}.{ts,json,yaml,yml} +``` + +
+ ![IntelliJ Prettier Settings](intellij-prettier.png){class=figure} +
Figure 2: IntelliJ Prettier Settings
+
diff --git a/docs/docs/development/index.md b/docs/docs/development/index.md deleted file mode 100644 index 6a49b418b9..0000000000 --- a/docs/docs/development/index.md +++ /dev/null @@ -1,400 +0,0 @@ -# Development - -Contributions are very much welcome. -But please follow the following guidelines and our [Code of Conduct](../code-of-conduct.md){target=_blank}. - -## Node.js - -We are using [Node.js](https://nodejs.org){target=_blank} version `14.13.0`. -To install node, use [nvm](https://github.com/nvm-sh/nvm){target=_blank} or [nvm-windows](https://github.com/coreybutler/nvm-windows){target=_blank}. - -```shell linenums="1" -nvm install v16.14.0 -nvm use 16.14.0 -``` - -## Repository - -The repository is a monorepo consisting of the CLI, server, docs and tests using the following commands. -We are using [Yarn 1 (Classic)](https://classic.yarnpkg.com/lang/en/){target=_blank}. - -```shell linenums="1" -git clone https://github.com/opentosca/opentosca-vintner.git -cd opentosca-vintner -git lfs install -git lfs pull -yarn --frozen-lockfile -``` - -## Large Files - -Larges files, such as binaries or archives used in examples, are added using [git lfs](https://git-lfs.com){target=_blank}. -This includes the following file extensions `.bin`, `.gz`, `.tar`, `.xz`, and `.zip`. - -## Branch Naming Convention - -Branches should be names as follows - -- `fix/short-title` for bug fixes -- `docs/short-title` for documentations -- `feature/short-title` for features -- `refactor/short-title` for refactoring -- `project/short-title` for thesis, EnPro or StuPro - -## Squash and Merge - -Please squash your commits into a single commit with a short but meaningful message and delete the branch afterwards. -The commit message should not have a link to the merge request. - -## GitHub Flow - -Our branching workflow follows [GitHub Flow](https://docs.github.com/de/get-started/quickstart/github-flow){target=_blank}. - -## Signed Commits - -Commits are required to be signed. -Therefore, you need to register a signing key. -For more information see -[Generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key){target=_blank}, -[Adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account){target=_blank}, -[Telling Git About Your Signing Key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key){target=_blank} -and [Signing Commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits){target=_blank}. - -You can enable auto-signing for a specific repository with the following command - -```shell linenums="1" -git config commit.gpgsign true -``` - -## JetBrains - -!!! Warning - WebStorm Version 2022.3.3 seems to have problems with breakpoints when `src/resolver/graph.ts` is involved. - However, WebStorm Version 2022.3.2 works fine. - -We recommend to use [IntelliJ IDEA](https://www.jetbrains.com/idea){target=_blank} -or [WebStorm](https://www.jetbrains.com/webstorm){target=_blank} installed -using [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app){target=_blank}. -Both are [for free](https://www.jetbrains.com/community/education/#students){target=_blank} for students. -Open the Project Settings using `Ctrl + Alt + S` to configure ESLint and Prettier. - -ESLint should be configured as given in the figure below with the following pattern. - -```text linenums="1" -{**/*,*}.{ts} -``` - -
- ![IntelliJ ESLint Settings](intellij-eslint.png){class=figure} -
Figure 1: IntelliJ ESLint Settings
-
- -Prettier should be configured as given in the figure below with the following pattern. - -```text linenums="1" -{**/*,*}.{ts,json,yaml,yml} -``` - -
- ![IntelliJ Prettier Settings](intellij-prettier.png){class=figure} -
Figure 2: IntelliJ Prettier Settings
-
- -## Command Line Interface - -!!! Info - `yarn cli` uses `src/cli/index.ts` while `yarn vintner` uses `build/cli/index.js`. - Therefore, run `yarn cli` to execute the current code without building it first. - -The CLI is build using [commander.js](https://github.com/tj/commander.js){target=_blank}. -The entry point is `src/cli/index.ts`. -To execute a CLI command during development, run - -```shell linenums="1" -yarn cli [command] [options] -``` - -## Server - -The server is build using [express](https://github.com/expressjs/express){target=_blank}. -The entry point is `src/server/index.ts`. -To run a development server on [http://localhost:3000](http://localhost:3000){target=_blank} with live-reload, run - -```shell linenums="1" -yarn server:serve -``` - -## Docs - -{{ linux_only_notice() }} - -The documentation is powered by [Material for MkDocs](https://squidfunk.github.io/mkdocs-material){target=_blank}. -Corresponding files are located in the `docs` directory. -Custom macros are implemented in `docs/macros.py` using [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io){target=_blank}. - -We expect that Python and [pandoc](https://pandoc.org){target=_blank} is already installed. -To install [pandoc](https://pandoc.org){target=_blank} on Ubuntu you might run - -```shell linenums="1" -sudo apt-get install pandoc -``` - -With the following command you can install `mkdocs-material` along with its requirements globally on your system. - -```shell linenums="1" -yarn docs:install -``` - -To start a local development server on [http://localhost:8000](http://localhost:8000){target=_blank}, run - -```shell linenums="1" -yarn docs:serve -``` - -Once the server is running, run the following command to open the docs in your browser - -```shell linenums="1" -yarn docs:open -``` - -To generate the documentation for the CLI and REST API, run the following command. -This command is also executed during the `release` workflow and, therefore, overwrites respective files. - -```shell linenums="1" -yarn docs:generate:interface -``` - -The documentation is build and published using GitHub Pages on pushes to the `main` branch. - -## Autogenerated Markdown - -Some Markdown files are autogenerated, e.g., [Dependencies](../dependencies.md){target=_blank} or [Interface](../interface.md){target=_blank}. -To warn the developer, include the following custom marco at the top of the template - -```text linenums="1" -{% raw %} -{{ autogenerated_notice('yarn docs:generate:licenses') }} -{% endraw %} -``` - -This will render the following warning, if the docs are served using `yarn docs:serve`. - -{{ autogenerated_notice('yarn docs:generate:licenses', True) }} - -Behind the scenes, the following Markdown is injected. - -```text linenums="1" -{{ autogenerated_notice('yarn docs:generate:licenses', True) }} -``` - -## Casts - -{{ linux_only_notice() }} - -The docs contain recorded demos. Thereby, we use the following tools - -- [asciinema](https://asciinema.org/){target=_blank} to record a terminal session -- [demo-magic](https://github.com/paxtonhare/demo-magic){target=_blank} to automate the terminal session -- [asciinema-player](https://github.com/asciinema/asciinema-player){target=_blank} embed casts in a standalone manner - -Casts are not recorded during any workflow. -The following command can be used to record the `home` cast for the landing page - -```shell linenums="1" -yarn docs:record:home -``` - -A cast can be embedded using the custom macro `asciinema_player` as follows inside a Markdown file. - -```text linenums="1" -{% raw %} -{{ asciinema_player('getting-started') }} -{% endraw %} -``` - -This will embed the cast `docs/docs/assets/casts/getting-started.cast` inside the page as follows. - -{{ asciinema_player('getting-started') }} - -Behind the scenes, the following HTML is injected. - -```text linenums="1" -{{ asciinema_player('getting-started') }} -``` - - -## Validate Service Template - -To validate a service template, run the following command. -This will install [puccini](https://github.com/tliron/puccini) in the background and execute its parser. -This only works on Linux or if WSL is installed. - -```shell linenums="1" -yarn puccini:validate:single path/to/service-template.yaml -``` - -To validate all registered service templates, run the following command. - -```shell linenums="1" -yarn puccini:check -``` - -## PlantUML - -We use [PlantUML](http://plantuml.com) for visualizing UML diagrams. -Read [PlantUML Guide](https://plantuml.com/de/guide) for modeling instructions. - -The following command plots all `.puml` files found in this repository using [PlantUML](http://plantuml.com). -This command is not executed in the pipeline since [mkdocs_build_plantuml](https://github.com/quantorconsulting/mkdocs_build_plantuml){target=_blank} to plot PUML when building mkdocs. - -```shell linenums="1" -yarn docs:plot:puml -``` - -The following command generates PUML files for registered service templates. -This command is executed in the pipeline. - -```shell linenums="1" -yarn docs:generate:puml -``` - -Note, for plotting SVGs we use the public PlantUML server https://www.plantuml.com/plantuml. -It is also possible to start a local PlantUML server using Docker. -Therefore, run the following command. - -```shell linenums="1" -yarn puml:up -``` - -However, you also need to configure the following environment variables in `docs/.env`. - -```yaml linenums="1" -MKDOCS_PUML_SERVER=http://localhost:8080 -MKDOCS_PUML_SERVER_SSL=true -``` - -## Tests - -We use [mocha](https://mochajs.org){target=_blank} and [chai](https://www.chaijs.com){target=_blank} for testing. -Respective tests are inside the `tests` directory. -To run the tests, use - -```shell linenums="1" -yarn test -``` - -To run the tests inside docker, use - -```shell linenums="1" -yarn test:docker -``` - -On pushes to the `main` branch these tests are executed. - -## Benchmark - -Run the following command, to run to benchmark the variability resolving. - -```shell linenums="1" -yarn benchmark -``` - -## Lint - -[ESLint](https://eslint.org){target=_blank} is used for linting. -To lint typescript, run the following command - -```shell linenums="1" -yarn lint:check -``` - -To fix lint problems, run the following command - -```shell linenums="1" -yarn lint:fix -``` - -## Code Style - -[Prettier](https://prettier.io){target=_blank} is used to format code. -To check the code style, run the following command - -```shell linenums="1" -yarn style:check -``` - -To fix code style problems, run the following command - -```shell linenums="1" -yarn style:fix -``` - -## Licenses - -[license-checker](https://github.com/davglass/license-checker){target=_blank} is used for handling licenses of ( -transitive) dependencies. -To check that (transitive) dependencies are licensed as expected, run the following command. -This check is also executed inside workflows. - -```shell linenums="1" -yarn licenses:check -``` - -To generate a list of licenses for all (transitive) dependencies, run the following command - -```shell linenums="1" -yarn docs:generate:licenses -``` - -The list includes information such as package name, version, license, etc. and is written to a CSV file. -At the same time, the [Dependencies](../dependencies.md){target=_blank} page is generated. -This command is also executed during the `release` workflow and, therefore, overwrites respective files. - -## Patch Packages - -We use [`patch-package`](https://github.com/ds300/patch-package){target=_blank} to fixing third party libraries. -For example, adding `logic-solver.d.ts` to [`logic-solver`](https://github.com/meteor/logic-solver){target=_blank}. -Therefore, make changes to the package inside `node_modules`, then run the following command. - -```shell linenums="1" -yarn patch-package ${package-name} -``` - -If you need to patch the `package.json`, then append the option `--exclude 'nothing'` as stated in [#311](https://github.com/ds300/patch-package/issues/311){target=_blank}. - -## Build - -To locally build the project, run the following command. -This will transpile Javascript inside the `/build` directory. - -```shell linenums="1" -yarn build -``` - -## Package - -{{ linux_only_notice() }} - -To locally package the project, run the following command. -This will package the previously transpiled Javascript using [`pkg`](https://github.com/vercel/pkg){target=_blank} and -generate binaries inside the `/dist` directory. - -```shell linenums="1" -yarn package -``` - -The issue considering the failed bytecode generation of MiniSat is known and can be ignored in our case. - -## Release - -On pushes to the `main` branch, the `release` workflow is triggered. -This workflow runs several tests, builds and packages the project and creates a new release. -Thereby, an existing release and `latest` tag is deleted. -There is only one release at total. -During the workflow the string `__VERSION__` inside a Javascript file is replace with the current commit hash. -The current version can be checked using `vintner --version`. - -## Night - -Every night, the `night` workflow is scheduled. -This workflow ensures that the latest release is correctly signed and can be executed. \ No newline at end of file diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 299f507b07..00471a091e 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -8,7 +8,7 @@ But it is possible to deploy applications using orchestrator plugins. ## How can I contribute? Contributions are very much welcome. -Please read [Development](./development){target=_blank}, and [Code of Conduct](code-of-conduct.md){target=_blank}. +Please read [Development](contributing/development){target=_blank} and [Code of Conduct](contributing/code-of-conduct.md){target=_blank}. ## Under which license is Vintner available? diff --git a/docs/docs/resources.md b/docs/docs/resources.md index 4b7f9429b7..544c89bc87 100644 --- a/docs/docs/resources.md +++ b/docs/docs/resources.md @@ -1,6 +1,6 @@ # Resources -This page contains a collection of interesting resources such as the TOSCA specifications, introductions, popular orchestrators and TOSCA repositories. +This document contains a collection of interesting resources such as the TOSCA specifications, introductions, popular orchestrators and TOSCA repositories. ## Specifications diff --git a/docs/macros.py b/docs/macros.py index f003197af7..6e07d484d4 100644 --- a/docs/macros.py +++ b/docs/macros.py @@ -45,4 +45,4 @@ def asciinema_player(cast): terminalFontSize: "13px" }); -""" % {"id": 'asciinema-player-' + cast, "url": fix_url('assets/casts/' + cast + '.cast')} +""" % {"id": 'asciinema-player-' + cast, "url": '/assets/casts/' + cast + '.cast'} diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index 3d61f4c08a..851a801245 100644 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -98,8 +98,8 @@ nav: - orchestrators.md - interface.md - dependencies.md - - development - GitHub: https://github.com/opentosca/opentosca-vintner + - Specifications: - Variability4TOSCA: - variability4tosca/motivation @@ -123,11 +123,17 @@ nav: - sofdcar/guides/zone - sofdcar/guides/location - TOSCA Simple Profile: https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3/os/TOSCA-Simple-Profile-YAML-v1.3-os.html + + - Contributing: + - contributing/setup.md + - contributing/development.md + - contributing/documentation.md + - contributing/code-of-conduct.md + - contributing/notes.md + - More Information: - OpenTOSCA: https://www.opentosca.org - - code-of-conduct.md - resources.md - publications.md - about-us - - notes.md - faq.md