The Jolie Documentation repository

This repository manages the Jolie documentation at https://docs.jolie-lang.org/.

If you want to update the documentation, this is not the repository that you are looking for. You have to update the branch of this repository for the relevant version of Jolie, e.g., for Jolie versions 1.10.x, you have to update the branch v1.10.x.

How to contribute to the documentation

Guidelines for creating examples

Naming conventions

outputPort: camelCase
- location: camelCase
- protocol: camelCase
- interfaces: camelCase
- aggregates: camelCase
- redirects: camelCase
- RequestResponse: CamelCase
- OneWay: CamelCase
inputPort: camelCase
- location: camelCase
- protocol: camelCase
- interfaces: camelCase
- aggregates: camelCase
- redirects: camelCase
- RequestResponse: CamelCase
- OneWay: CamelCase
ServiceName: CamelCase
TypeName: CamelCase
Interfaces: CamelCase
- RequestResponse: CamelCase
- OneWay: CamelCase
operations: camelCase
variables: camelCase
package-name: kebab-case
module-name: kebab-case
CONSTANTS: SCREAMING_SNAKE_CASE
define: camelCase
private: camelCase

Request message assignment

Try to write the message request using inline syntax whenever possible. Ex:

readFile@file( { filename = "test.txt" } )( response )

instead of

request.filename = "test.txt"
readFile@File( request )( response )

Use multiple lines if necessary

writeFile@File( {
filename = "text.txt"
content = "this is a test message"
} )()

Use deep copy or with in case the request message has several nodes

request << {
    node1 = "node1"
    node2 = "node2"
    node3 = "node3"
    ...
}

with( request ) {
    node1 = "node1";
    node2 = "node2";
    node3 = "node3";
    ...
}

Fixing a tutorial

Create a branch named as it follows
- tutorials/fix/name-of-the-tutorial

Creating a new tutorial

Define a branch name that follows this guideline tutorials/new/short-tutorial-name
Actions to take in repo jolie/examples
- Create a branch with the name tutorials/new/short-tutorial-name
- Checkout branch tutorials/new/short-tutorial-name
- Go to folder examples/v1.10.x/tutorials/
- Create a directory with the short name of the tutorial mkdir short-tutorial-name
- Go to folder examples/v1.10.x/tutorials/short-tutorial-name
- Create all the files necessary for the tutorial
- Commit
Actions to take in repo jolie/docs
- Checkout branch v.1.10.x
- Starting from this branch create a new branch tutorials/new/short-tutorial-name
- Checkout branch tutorials/new/short-tutorial-name
- Go to folder docs/web/tutorials/
- Create a directory with the short name of the tutorial mkdir short-tutorial-name
- Go to folder docs/web/tutorials/short-tutorial-name
- Create file README.md as starting file for the tutorial. Start to write down the tutorial in this file
  - Remember to add links to the examples previously created in examples/v1.10.x/tutorials/short-tutorial-name
  - if you need to add links to other existing pages of the docs, please insert the URL of the page, not the path
  - If you need to add images:
    Go into folder docs/src/images/
    Select a .svg file which is close to the diagram you want to create
    Open the file with the open version of inkscape
    Copy the file into a new file, giving it a new filename
    Close the file and open the new one, starting to editing it as you prefer
    Remember to use font Segoe Print for comments
    Remember to use tool free hand lines (setting bevel effect around 50) for tracing arrows for connecting comments and drawings
    Remember to use squared lines for connecting microservices together
    Once edited:
    Save the .svg file into folder docs/src/images/ (it is the source)
    Save the .png file into folder docs/web/assets/
    Create a link in the doc to png file. Example of a link:
    ![](https://raw.githubusercontent.com/jolie/docs/v1.10.x/web/.gitbook/assets/using_dependencies_01.png)
- Once edited the documentation, open file docs/web/SUMMARY.md and place the link of your tutorial under main item Tutorial. Tru to find a correct placement of the tutorial considering the fact the previous tutorials must give the minimal knowledge necessary to understand our tutorial
Open a pull request

Last updated 1 year ago