Skip to content

Commit

Permalink
fix: revise the format and fix typos
Browse files Browse the repository at this point in the history
  • Loading branch information
@trgiangdo
trgiangdo committed Jun 5, 2023
1 parent 8388099 commit 1427a59
Show file tree
Hide file tree
Showing 4 changed files with 102 additions and 123 deletions.
20 changes: 9 additions & 11 deletions docs/manuals/core/versioning/development_mode.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,23 @@ Developing an application in Taipy often requires changing the configuration mul
Data from a previous run are incompatible with the configuration changes. They should then be
deleted to try the new configuration version.

In _development_ mode, Taipy automatically deletes old entities attached to a previous development
In *development* mode, Taipy automatically deletes old entities attached to a previous development
version before running the application. This ensures a fresh start for the application. When running
an application in _development mode_, a development version is created.
an application in development mode, a development version is created.

In the following, we consider the basic Taipy Core application `main.py`:
In the following, we consider a basic Taipy Core application `main.py`:

```python linenums="1"
```python linenums="1" title="main.py"
{%
include-markdown "./code_example/main.py"
comments=false
%}
```

By default, a Taipy Core application runs in _development_ mode, but you can also run a
Taipy application on your command line interface with `--development` or `-dev` option.
By default, a Taipy Core application runs in development mode. You can also explicitly define the
development mode by running your Taipy application with `--development` or `-dev` option on the CLI.

```console
$ taipy manage-versions --list
Version number Mode Creation date
9b01399c-67e4-41a4-83d3-121f7210d4e7 Development (latest) 2023-01-23 23:44:04

$ python main.py
[2023-01-24 23:46:29,468][Taipy][INFO] Development mode: Clean all entities of version 9b01399c-67e4-41a4-83d3-121f7210d4e7
[2023-01-24 23:46:29,615][Taipy][INFO] job JOB_my_print_algo_9d75018a-1803-4358-8530-e62641e00ed8 is completed.
Expand All @@ -33,7 +29,9 @@ Version number Mode Creation date
9b01399c-67e4-41a4-83d3-121f7210d4e7 Development (latest) 2023-01-23 23:46:29
```

In the example above, `python main.py` command runs the application in development mode.
In the example above, `python main.py` command runs the application in development mode. The
command `taipy manage-versions --list` lists all versions of your current Taipy Core application
(see the [Manage versions on Taipy CLI page](../../cli.md#manage-versions) for more details).

The output on the console indicates that all entities of the development version
`9b01399c-67e4-41a4-83d3-121f7210d4e7` are deleted before running the application.
Expand Down
101 changes: 45 additions & 56 deletions docs/manuals/core/versioning/experiment_mode.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
With _experiment_ mode, you can save and name your application as an _experiment_ version.
When running an _experiment_ version in _experiment_ mode, Taipy only considers the
entities attached to this version. It filters out all other entities from different
versions, so you can continue your development process without worrying about losing
entities of your other versions.
With *experiment* mode, you can save and name your application as an experiment version.
When running an experiment version in experiment mode, Taipy only considers the entities attached
to this version. It filters out all other entities from different versions, so you can continue your development process without worrying about losing entities of your other versions.

!!! note "Use case"

The _experiment_ mode is handy in the process of improving a stable
The experiment mode is handy in the process of improving a stable
version of a Taipy application. In that case, you need to run one or multiple
experiments like tuning algorithm parameters, updating configuration by adding
KPI data nodes, testing new algorithms, etc. These require some configuration
Expand All @@ -18,9 +16,9 @@ entities of your other versions.
application eventually with some configuration changes without deleting the
experiment's entities.

In the following, we consider the basic Taipy Core application `main.py`:
In the following, we consider a basic Taipy Core application `main.py`:

```python linenums="1"
```python linenums="1" title="main.py"
{%
include-markdown "./code_example/main.py"
comments=false
Expand All @@ -29,8 +27,7 @@ comments=false

# Create a version

To create an _experiment_ version you can run a Taipy application on your command line
interface with `--experiment` option.
To create an experiment version, you can run your Taipy application with `--experiment` option on the CLI.

```console
$ taipy manage-versions --list
Expand All @@ -47,15 +44,16 @@ Version number Mode Creation date
26e56e84-9e7e-4a26-93f6-443d9aa541d9 Development 2023-01-25 12:20:33
```

An _experiment_ version is created and stored. As you can see the number of scenarios
displayed is 1. That means Taipy only considers the scenarios of the _experiment_
version, and filters out the entities of the other development version. By default,
a random name is used to identify the version of your application.
As indicated by th output of `taipy manage-versions --list` command, a new experiment version is
created and stored. As you can see, the number of scenarios displayed is 1. That means Taipy only
considers the scenarios of the experiment version, and filters out the entities of the other
development version.

By default, a random name is used to identify the version of your application.

# Name a version

You can explicitly define the name of an _experiment_ version by providing the name
in the command line.
You can explicitly define the name of an experiment version by providing the name in the CLI.

```console
$ taipy manage-versions --list
Expand All @@ -74,18 +72,20 @@ Version number Mode Creation date
26e56e84-9e7e-4a26-93f6-443d9aa541d9 Development 2023-01-25 12:20:33
```

With `--experiment 1.0` option, an _experiment_ version is created and stored under
the name "1.0".
With the `--experiment 1.0` option, an experiment version is created and stored under the name "1.0".

In this example, you can see the number of scenarios displayed is still 1. Taipy
only considered the scenarios of the 1.0 version, and filters out the entities of
other versions.
In this example, you can see the number of scenarios displayed is still 1. Taipy only considered
the scenarios of the 1.0 version, and filters out the entities of other versions.

# Run an existing version

To run an existing _experiment_ version, the configuration of the application must
be the same. No change must be done. You can run a Taipy application on your
command line interface with `--experiment VERSION` option and the name of the existing version.
To run an existing experiment version, there **must not** be any breaking change in the configuration of the application. Any change on the configuration is considered breaking change, except for:
- Changes in the job execution configuration.
- Changes in the GUI configuration.
- Changes in the Core configuration.

You can run a Taipy application on the CLI with `--experiment` option and following by the name of
the existing version.

```console
$ taipy manage-versions --list
Expand All @@ -97,23 +97,16 @@ Version number Mode Creation date
$ python main.py --experiment 1.0
[2023-01-25 12:28:54,963][Taipy][INFO] job JOB_my_print_algo_2133dc18-643b-4351-872b-aedfc2c65c9c is completed.
nb scenarios: 2

$ taipy manage-versions --list
Version number Mode Creation date
1.0 Experiment (latest) 2023-01-25 12:24:19
325d0618-6f9e-459b-9597-48fa93a57a23 Experiment 2023-01-25 12:20:56
26e56e84-9e7e-4a26-93f6-443d9aa541d9 Development 2023-01-25 12:20:33
```

As you can see, this time the number of scenarios displayed is 2. Indeed, we run
the 1.0 version twice, so we have two scenarios attached to it. Scenarios from other
versions are filtered out.
As you can see, this time the number of scenarios displayed is 2. Indeed, we run the 1.0 version
twice, so we have two scenarios attached to it.

# Clean entities of an existing version

To run an _experiment_ version with a fresh start, you can run on _experiment_
mode with `--clean-entities` option. Taipy deletes the entities of the version
provided before running the application again.
To run an experiment version with a fresh start, you can run on experiment mode with the
`--clean-entities` option. Taipy deletes the entities of the version provided before running the
application again.

```console
$ taipy manage-versions --list
Expand All @@ -135,14 +128,13 @@ Version number Mode Creation date
```

As you can see in the previous example the number of scenarios became 1 again. Indeed,
Taipy cleaned all entities of that _experiment_ version before running it again (which
Taipy cleaned all entities of that experiment version before running it again (which
created a new scenario).
Scenarios from other versions are not deleted and still filtered out.

# Change config of an existing version

As explained before, there is a constraint when re-running an existing version.
The configuration of the application must be the same. No change must be made.
As explained before, there is a constraint when re-running an existing version. The configuration
of the application must be the same. There must be no breaking change.

But don't worry; if there is any change to your configuration, Taipy will show
a warning message before exiting.
Expand All @@ -151,7 +143,7 @@ Let's assume a change has been made in the configuration in `main.py`. A custom
property (`description`) has been added to the output data node config. Here is
the new configuration.

```python linenums="1"
```python linenums="1" title="main.py"
{%
include-markdown "./code_example/main_with_changes.py"
comments=false
Expand All @@ -167,11 +159,10 @@ Added object:
To force running the application with the changes, run your application with --taipy-force option.
```

In the example above, when re-running version 1.0, Taipy detects and displays all
the differences, so you precisely know what has been changed and can decide what
to do. Either you revert your configuration changes, or you can run the application
with the `--taipy-force` option to force Taipy to update the configuration of the provided
version before re-running the application.
In the example above, when re-running version 1.0, Taipy detects and displays all the differences,
so you precisely know what has been changed and can decide what to do. Either you revert your
configuration changes, or you can run the application with the `--taipy-force` option to force
Taipy to update the configuration of the provided version before re-running the application.

```console
$ python main.py --experiment 1.0 --taipy-force
Expand All @@ -186,15 +177,13 @@ the configuration. A new scenario has been created.

!!! Warning

By forcing the configuration update, you must be aware that old entities
instantiated before the configuration change may not be compatible.
By forcing the configuration update, you must be aware that old entities instantiated before
the configuration change may not be compatible.

On the previous example, note that two scenarios are attached to version
1.0. Similarly, two `output` data nodes as well. One has been instantiated
before the configuration update and one after. That means the `description`
property only exists for one of the two `output` data nodes. It is your
responsibility to handle the changes.
On the previous example, note that two scenarios are attached to version 1.0, and two `output`
data nodes as well. One has been instantiated before the configuration update and one after.
That means the `description` property only exists for one of the two `output` data nodes.
It is your responsibility to handle the changes.

Hint: you can migrate your old entities so they become compatible with the
new configuration or you can ensure your code is compatible with both versions
of data nodes.
Hint: You can migrate your old entities so they become compatible with the new configuration or
you can ensure your code is compatible with both versions of data nodes.
64 changes: 28 additions & 36 deletions docs/manuals/core/versioning/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,46 +13,38 @@ configuration.

Taipy proposes a **version management system** to:

- Create or re-use a version when running a Taipy application (Refer to
[Run with a version name](version-mgt.md) Page)
- Manage the different versions of the configuration across the application runs
(Refer to [Run with a version name](../../cli.md#Manage-versions) Page),
- Keep track of the old versions used to instantiate old entities
(Refer to [Run with a version name](../../cli.md#Manage-versions) Page),
- Create or re-use a version when running a Taipy application.
- Manage the different versions of the configuration across the application runs (see the [Manage versions on Taipy CLI page](../../cli.md#manage-versions) for more details).

## Modes

Taipy requires a _mode_ to run. A _mode_ corresponds to how Taipy behaves at runtime
regarding old entities instantiated in previous runs. Three
runtime modes can be used to run a Taipy application.

- Using the `development` mode (default mode), Taipy drops all old entities before
running the application.
It is made to help users during the application development phase to implement its
application through successive iterations of configuration changes. Please refer to
the [development mode](./development_mode.md) documentation page for more details.

- Using the `experiment` mode, Taipy keeps old entities untouched but filters them out
when running the application. The application behaves like there are no old entities.
Only the entities created during the current run are considered by the application.
It is designed to help the user improve an existing application by experimenting
with possible configuration changes, trying new algorithms, investigating the impacts
of a parameter change, etc. Please refer to the [experiment mode](./experiment_mode.md)
documentation page for more details.

- Using the `production` mode, Taipy considers all existing entities, whether they have
been instantiated in the current run or in a previous one.
It is designed to run an application in a production environment with existing entities
created in previous runs. Please refer to the [production mode](./production_mode.md)
documentation page for more details.
Taipy requires a *mode* to run. A mode corresponds to how Taipy behaves at runtime regarding old
entities instantiated in previous runs. There are three runtime modes that can be used when running
a Taipy application.

- In development mode (default mode), Taipy drops all old entities before running the application.
It is made to help users during the application development phase to implement its application
through successive iterations of configuration changes. Please refer to the
[development mode](./development_mode.md) documentation page for more details.

- In experiment mode, Taipy keeps old entities untouched but filters them out when running the
application. The application behaves like there are no old entities. Only the entities created
during the current run are considered by the application. It is designed to help the user improve
an existing application by experimenting with possible configuration changes, trying new
algorithms, investigating the impacts of a parameter change, etc. Please refer to the
[experiment mode](./experiment_mode.md) documentation page for more details.

- In production mode, Taipy considers all existing entities, whether they have been instantiated in
the current run or in a previous one. It is designed to run an application in a production
environment with existing entities created in previous runs. Please refer to the
[production mode](./production_mode.md) documentation page for more details.

## Versions

A _version_ is basically made of a _mode_ and a configuration (`Config^`). The various
_versions_ are used to track the configuration changes with respect to old entities.
Each Taipy entity is assigned to a unique _version_.
A *version* is basically made of a *mode* and a configuration (`Config^`). The various versions
are used to track the configuration changes with respect to old entities. Each Taipy entity is
assigned a unique version.

At runtime, Taipy uses a _version_ either by creating a new one or retrieving an
existing one. It depends on the runtime _mode_ used to run the application and on the
configuration changes.
This runtime _version_ is assigned to new entities created.
At runtime, Taipy uses a version either by creating a new one or retrieving an existing one. It
depends on the runtime mode used to run the application and on the configuration changes. This
runtime version is assigned to new entities created.
Loading

0 comments on commit 1427a59

Please sign in to comment.