Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[Workflow] Rework a bit the doc #12295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 24, 2019
Merged

[Workflow] Rework a bit the doc #12295

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion _build/redirection_map
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,8 @@
/console/logging /console
/frontend/encore/legacy-apps /frontend/encore/legacy-applications
/contributing/code/patches /contributing/code/pull_requests
/workflow/state-machines /workflow/introduction
/workflow/state-machines /workflow/workflow-and-state-machine
/workflow/introduction /workflow/workflow-and-state-machine
/workflow/usage /workflow
/introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony
/contributing/community/other /contributing/community
Expand Down
2 changes: 1 addition & 1 deletion reference/configuration/framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2365,7 +2365,7 @@ type
**type**: ``string`` **possible values**: ``'workflow'`` or ``'state_machine'``

Defines the kind of workflow that is going to be created, which can be either
a normal workflow or a state machine. Read :doc:`this article </workflow/introduction>`
a normal workflow or a state machine. Read :doc:`this article </workflow/workflow-and-state-machine>`
to know their differences.

.. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html
Expand Down
21 changes: 14 additions & 7 deletions workflow.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Workflow

Using the Workflow component inside a Symfony application requires to know first
some basic theory and concepts about workflows and state machines.
:doc:`Read this article </workflow/introduction>` for a quick overview.
:doc:`Read this article </workflow/workflow-and-state-machine>` for a quick overview.

A workflow is a process or a lifecycle that your objects go through. Each
step or stage in the process is called a *place*. You do also define *transitions*
Expand Down Expand Up @@ -158,13 +158,20 @@ As configured, the following property is used by the marking store::

The marking store type could be "multiple_state" or "single_state". A single
state marking store does not support a model being on multiple places at the
same time.
same time. This means a "workflow" must use a "multiple_state" marking store
and a "state_machine" must use a "single_state" marking store. Symfony
configures the marking store according to the "type" by default, so it's
preferable to not configure it.

A single state marking store use a string to store the data. A multiple
state marking store use an array to store the data.

.. tip::

The ``type`` (default value ``single_state``) and ``arguments`` (default
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced with this tip + previous note.
There is too much to way about the marking store.
Chould we add a new chapter (in this page OC) instead?

value ``marking``) attributes of the ``marking_store`` option are optional.
If omitted, their default values will be used.
The ``marking_store.type`` (the default value depends on the ``type`` value)
and ``arguments`` (default value ``['marking']``) attributes of the
``marking_store`` option are optional. If omitted, their default values will
be used. It's highly recommenced to use the default value.

.. tip::

Expand Down Expand Up @@ -493,5 +500,5 @@ Learn more
.. toctree::
:maxdepth: 1

workflow/introduction
workflow/dumping-workflows
/workflow/workflow-and-state-machine
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change could be reverted, but it's stange to have an introduction that is not main entry point. More over there are no links at the end of the page.

/workflow/dumping-workflows
2 changes: 0 additions & 2 deletions workflow/introduction.rst → workflow/workflow-and-state-machine.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,6 @@ your model. The most important differences between them are:

* Workflows can be in more than one place at the same time, whereas state
machines can't;
* Workflows usually don't have cyclic paths in the definition graph, but it's
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is wrong

Copy link
Member

@Nyholm Nyholm Sep 10, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No.. I would say this is very true. But maybe we can express it differently.

Workflows usually have a defined start and end. State machines usually keep running forever.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still disagree. Why do you say a State Machine keep running? I had many state machine that have a start and a end too

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

both workflow or state machine are either cyclic or straight forward, no?
for me the only difference is the state representation, single or multiple
but not transitions process

Copy link
Member

@Nyholm Nyholm Sep 10, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had many state machine that have a start and a end too

That does not make you correct. =)

A mathematician would disagree with you.

But as you say, one can probably use Workflow and StateMachine interchangeably. But you should always know what you are using to know how to relate to your object.

Why do you say a State Machine keep running?

See Wikipeida on Petri net > Work flow net.

WF-nets have the soundness property,[20] indicating that a process with a start marking of k tokens in its source place, can reach the termination state marking with k tokens in its sink place (defined as K-sound WF-net). Additionally, all the transitions in the process could fire (i.e., for each transition there is a reachable state in which the transition is enabled).

That is not usually the case for a state machine.

I may be wrong saying "a State Machine keep running". But the opposite is true. A Workflow has an end. A state machine does not need one.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. But I don’t like the idea that this bullet (or a version of it) is removed.

This is the place where we state the differences and help people choose implementation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree. The difference is when you need 1 or many places at the same time.
Or in an other shape: It's when you can parallelism or not

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As someone who doesn't know much about Workflows, a phrase like the following proposed by Tobias would be easy to understand for me:

Workflows usually have a defined start and end. State machines usually keep running forever.

Also, the phrase says "usually" instead of "always / never", "can / can't", etc. so I guess it's compatible with what @lyrixx is saying too.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm really sorry to insist but the main difference is not about this point.
For most application a state machine is enough because there are no parallelism. Then if the need is real, a workflow better fit.

A workflow is more powerful but it comes with more complexity. Some people doesn't understand the sentence "the object must be in all place before the transition". (I'm on my phone, it's hard to make a link)But see related issue about that.

I agree the sentence is totally valid in theory but the choose should not be based on this fact.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed my mind. I'm in favour of removing this line.

I still think this line is correct. But it is too complex, not very important and easily misunderstood.

(I just had a conversation with a person referring to this line and said "workflows cannot have loops".)

common for state machines;
* In order to apply a transition, workflows require that the object is in all
the previous places of the transition, whereas state machines only require
that the object is at least in one of those places.
Expand Down