Skip to content

Added docs for Workflow component #6871

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

Closed
wants to merge 38 commits into from
Closed

Added docs for Workflow component #6871

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
d0701f0
Added docs for Workflow component
Nyholm Aug 12, 2016
91867c2
Moved images
Nyholm Aug 12, 2016
69bca59
Fixes
Nyholm Aug 12, 2016
f99fbb2
Fixes
Nyholm Aug 12, 2016
e797f0c
Syntax error
Nyholm Aug 12, 2016
5b2a029
Cleanup and minor fixes
Nyholm Aug 16, 2016
196baf9
Separated docs for component
Nyholm Aug 16, 2016
763950d
Updating docs to using symfony services
Nyholm Aug 16, 2016
cead2f7
Added docs about registry
Nyholm Aug 16, 2016
e0089c5
Added placeholders
Nyholm Aug 16, 2016
48de43d
Added note about state machines
Nyholm Aug 16, 2016
805b237
Added example with twig
Nyholm Aug 16, 2016
f57ec14
Show Twig function workflow_transitions
Nyholm Aug 16, 2016
03925ff
syntax fix
Nyholm Aug 16, 2016
e6bdee6
Some syntax fixes and a better "why do we need this"
Nyholm Nov 7, 2016
c7464c7
typos
Nyholm Nov 7, 2016
83d26c1
toctree fix
Nyholm Nov 7, 2016
6e7a35f
Fixed typos and comments
Nyholm Nov 8, 2016
4415466
Added usage example on the component
Nyholm Nov 8, 2016
866b25a
Added example how to dump with Symfony
Nyholm Nov 8, 2016
dceebec
Added examples of workflows
Nyholm Nov 8, 2016
b959f8a
Updated state machine with an example
Nyholm Nov 8, 2016
b45edf2
simplify job_application
Nyholm Nov 8, 2016
fefdb5f
syntax
Nyholm Nov 9, 2016
7f0f5b0
Added comment about the service name
Nyholm Nov 9, 2016
c681283
Updated accoding to feedback
Nyholm Nov 9, 2016
86ecf0a
Added PHP config
Nyholm Nov 9, 2016
d002a8b
Added xml and PHP config
Nyholm Nov 9, 2016
b0a8855
Added workflow under guides
Nyholm Nov 9, 2016
4e7cf11
Removed the *why workflows* from the usage page.
Nyholm Nov 9, 2016
3aa433d
Documented support for DefinitionBuilder
Nyholm Nov 9, 2016
4f277dc
fixed typo
Nyholm Nov 9, 2016
2511c21
Merge pull request #1 from Nyholm/workflow-definition-builder
Nyholm Nov 9, 2016
c9b1656
Updated to support changes in https://github.com/symfony/symfony/pull…
Nyholm Nov 9, 2016
2cc2934
Updated twig example
Nyholm Nov 9, 2016
47dc11d
show how to configure the DI extension config
Nyholm Nov 11, 2016
3250621
Fixed typos
Nyholm Nov 11, 2016
c0bd6da
Use imperative instead of past tense.
Nyholm Nov 11, 2016
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
Prev Previous commit
Next Next commit
Updated state machine with an example
  • Loading branch information
@Nyholm
Nyholm committed Nov 8, 2016
commit b959f8a7ef27eb932116f08f168ee6f38b51c69c
Binary file added _images/components/workflow/pull_request.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 44 additions & 30 deletions workflow/state-machines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,45 +11,59 @@ one place simultaneously. It is also worth noting that a workflow does not
commonly have cyclic path in the definition graph but it is common for a state
Copy link
Member

Choose a reason for hiding this comment

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

"[...] definition graph, but it [...]"

machine.

Example of state machine
Copy link
Member

Choose a reason for hiding this comment

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

"Example of a State Machine"

------------------------

Consider the states a GitHub pull request may have. We have an initial "start"
state, a state for running tests on "travis", then we have the "review" state
where we can require changes, reject or accept the pull request. At anytime we
could also "update" the pull request which will result in another "travis" run.
Copy link
Member

Choose a reason for hiding this comment

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

Please remove the first-person usage:

A pull request starts in an intial "start" state, a state for e.g. running
tests on Travis. When this is finished, the pull request is in the "review"
state, where contributors can require changes, reject or accept the
pull request. At any time, you can also "update" the pull request, which
will result in another Travis run.

Copy link
Member Author

Choose a reason for hiding this comment

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

Thank you


.. image:: /_images/components/workflow/pull_request.png

Below is the configuration for the pull request state machine.

.. configuration-block::

.. code-block:: yaml

framework:
Copy link
Member

Choose a reason for hiding this comment

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

please add # app/config/config.yml

workflows:
blog_publishing:
type:
type: 'state_machine'
supports:
- AppBundle\Entity\BlogPost
places:
- draft
pull_request:
type: 'state_machine'
marking_store:
type: scalar
supports:
- AppBundle\Entity\PullRequest
places:
- start
Copy link
Contributor

Choose a reason for hiding this comment

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

I've started with many comments, so here a resume of what I suggest for the following:

pull_request:
    type: 'state_machine'
    supports:
        - AppBundle\Entity\PullRequest
    places:
        - started
        - coding
        - travis
        - needs_review
        - reviewed
        - merged
        - closed
    transitions:
        test:
            from: [started, coding]
            to: travis
        submit:
            from: travis
            to: needs_review
        request_change:
            from: [travis, needs_review, reviewed]
            to: coding
        accept:
            from: needs_review
            to: reviewed
        reject:
            from: [coding, needs_review, reviewed]
            to: closed
        reopen:
            from: closed
            to: needs_review
        merge:
            from: reviewed
            to: merged

Wdyt?

Actually when trying to dump it I've found a bug and submitted symfony/symfony#20497 :)

- coding
- travis
- review
- rejected
- published
transitions:
to_review:
from: [draft, rejected]
to: review
publish:
- merged
- closed
transitions:
submit:
from: start
to: travis
update:
from: [coding, travis, review]
to: travis
wait_for_reivew:
from: travis
to: review
change_needed:
from: review
to: published
reject:
to: coding
accepted:
from: review
to: rejected


With the configuration above we allow an object in place ``draft`` **or**
``rejected`` to be moved to ``review``. If the marking store had been of
type ``scalar`` the object had to be in **both** places. ::

$workflow = $this->container->get('state_machine.blog_publishing');
$post = new \BlogPost();

$post->state = 'draft';
$workflow->can($post, 'to_review'); // True
to: merged
rejected:
from: review
to: closed
reopened:
Copy link
Member

Choose a reason for hiding this comment

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

What do you think about renaming the last four transitions to request_change, accept, reject, and reopen as we are describing actions and not events that just happened?

Copy link
Member Author

Choose a reason for hiding this comment

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

👍 You are correct

from: closed
to: review
Copy link
Member

Choose a reason for hiding this comment

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

please add XML and PHP formats.

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="utf-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>

    <framework:config>
        <framework:workflow name="pull_request" type="state_machine">
            <framework:marking-store type="scalar"/>

            <framework:support>AppBundle\Entity\PullRequest</framework:support>

            <framework:place>start</framework:place>
            <framework:place>coding</framework:place>
            <framework:place>travis</framework:place>
            <framework:place>review</framework:place>
            <framework:place>merged</framework:place>
            <framework:place>closed</framework:place>

            <framework:transition name="submit">
                <framework:from>start</framework:from>

                <framework:to>travis</framework:to>
            </framework:transition>

            <framework:transition name="update">
                <framework:from>coding</framework:from>
                <framework:from>travis</framework:from>
                <framework:from>review</framework:from>

                <framework:to>travis</framework:to>
            </framework:transition>

            <framework:transition name="wait_for_review">
                <framework:from>travis</framework:from>

                <framework:to>review</framework:to>
            </framework:transition>

            <framework:transition name="change_needed">
                <framework:from>review</framework:from>

                <framework:to>coding</framework:to>
            </framework:transition>

            <framework:transition name="accepted">
                <framework:from>review</framework:from>

                <framework:to>merged</framework:to>
            </framework:transition>

            <framework:transition name="rejected">
                <framework:from>review</framework:from>

                <framework:to>closed</framework:to>
            </framework:transition>

            <framework:transition name="reopened">
                <framework:from>closed</framework:from>

                <framework:to>review</framework:to>
            </framework:transition>

        </framework:workflow>

    </framework:config>
</container>

Copy link
Member Author

Choose a reason for hiding this comment

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

Thank you. Im embarrassingly bad at the XML syntax for the config.


$post->state = 'rejected';
$workflow->can($post, 'to_review'); // True

.. _Petri net: https://en.wikipedia.org/wiki/Petri_net