Added an initial documentation for Symfony Flex recipes #6

javiereguiluz · 2017-04-05T09:19:14Z

It's based on your blog posts and the source code of Flex.

fabpot · 2017-04-06T18:02:18Z

I've just added one more option: version_aliases. Right now, there is only one recipe using it, phpunit. Basically, it lists all additional versions that work with the recipe.

For Symfony, instead of duplicating all recipes when 3.4 is out, we can just add it to version_aliases for each 3.3 recipe. If one recipe should be different, then we need to duplicate the recipe (we might want to use symlinks to avoid too many duplications though).

fabpot · 2017-04-07T20:09:28Z

README.rst

+.. code-block:: json
+
+    {
+        "version_aliases": ["3.3", "3.4", "4.0-dev"]


should be "4.0".

fabpot · 2017-04-11T02:29:27Z

README.rst

+``aliases`` option
+~~~~~~~~~~~~~~~~~~
+
+The main configuration option is called ``aliases`` and its value is an array


Not sure that this is the main configuration option

fabpot · 2017-04-11T02:29:52Z

README.rst

+
+Developers can now install this dependency as ``composer require acme-log``. For
+security reasons, and to improve Symfony's developer experience, a long list of
+aliases are reserved by Symfony Flex (``orm``, ``mailer``, ``loger``, ``admin``,


fabpot · 2017-04-11T02:30:37Z

README.rst

+Developers can now install this dependency as ``composer require acme-log``. For
+security reasons, and to improve Symfony's developer experience, a long list of
+aliases are reserved by Symfony Flex (``orm``, ``mailer``, ``loger``, ``admin``,
+etc.) If you use those aliases in your recipe, they will be ignored.


Not sure we need this paragraph as we will be accepting or rejecting recipes before they get merged, so that's just a matter of reviewing the aliases.

fabpot · 2017-04-11T02:31:11Z

README.rst

+
+This option lists all the additional versions of the dependency that work with
+this very same recipe (versions can use any of the syntaxes supported by
+Composer). This avoids duplicating recipes when a new version of the package is


Versions should only be like x.y.

We should also probably add a note about the fact that the main version used as a directory should be the oldest supported version.

fabpot · 2017-04-11T02:33:00Z

README.rst

+Enables one or more bundles in the Symfony application by appending them to the
+``bundles.php`` file. Its value is an associative array with the bundle
+namespace as the keys and the array of environments where it must be enabled as
+the value. Use ``all`` to enable the bundle in any existing environment:


We should probably list all possible values. We do accept any values, but I think we need to restrict to the "default" supported Symfony envs: dev, test, prod.

fabpot · 2017-04-11T02:33:43Z

README.rst

+The ``%BIN_DIR%`` string is a special value that it's turned into the absolute
+path of the binaries directory of the Symfony application. These are the special
+variables available: ``BIN_DIR``, ``CONF_DIR``, ``ETC_DIR``, ``SRC_DIR`` and
+``WEB_DIR``. You can also access to any variable defined in the ``extra`` section


I would add the % sign so that people can copy/paste them directly.

fabpot · 2017-04-11T02:34:39Z

README.rst

+            "DB_HOST": "127.0.0.1",
+            "DB_NAME": "symfony",
+            "DB_USER": "root",
+            "DB_PASSWORD": ""


Perhaps we can change the example as DB_ vars are now different.

fabpot · 2017-04-11T02:35:38Z

README.rst

+to execute them automatically when running ``composer install`` and ``composer update``.
+The value is an associative array where the key is the script to execute (including
+all its arguments and options) and the value is the type of script (``php-script``
+for PHP scripts, ``script`` for Makefile tasks and ``symfony-cmd`` for Symfony


script can really be any shell script, not just a make task.

fabpot · 2017-04-11T02:36:07Z

README.rst

+file and wrapped with section separators (``###> your-recipe-name-here ###``)
+that must not be removed or modified.
+
+``post-install-output`` configurator


I would use Configurator with a capital letter.

stof · 2017-04-11T07:42:40Z

README.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This option lists all the additional versions of the dependency that work with
+this very same recipe (versions can use any of the syntaxes supported by


the sentence inside parenthesis is wrong

stof · 2017-04-11T07:47:23Z

README.rst

+
+Enables one or more bundles in the Symfony application by appending them to the
+``bundles.php`` file. Its value is an associative array with the bundle
+namespace as the keys and the array of environments where it must be enabled as


this is the bundle class name, not the bundle namespace

stof · 2017-04-11T07:50:30Z

README.rst

+The ``%BIN_DIR%`` string is a special value that it's turned into the absolute
+path of the binaries directory of the Symfony application. These are the special
+variables available: ``BIN_DIR``, ``CONF_DIR``, ``ETC_DIR``, ``SRC_DIR`` and
+``WEB_DIR``. You can also access to any variable defined in the ``extra`` section


We should give access only to extras containing a scalar value (currently, we don't validate it in symfony/flex, but an array would give you a notice and Array when casting it)

stof · 2017-04-11T07:52:32Z

README.rst

+Symfony Flex turns that recipe into the following content appended to the ``.env``
+and ``.env.dist`` files:
+
+.. code-block:: ini


bash would be better than ini, as the syntax of the .env file is based on Bash (it is meant to allow using source .env too in case you use explicit exports)

stof · 2017-04-11T07:58:40Z

README.rst

+        ]
+    }
+
+.. _`Symfony Flex`: https://github.com/fabpot/flex


Is it expected to stay there ? If we want to move it to the symfony org as soon as it is open-sourced, I suggest using directly the target URL to avoid forgetting to update it

fabpot · 2017-04-11T14:52:45Z

README.rst

+All the contents of the ``manifest.json`` file are optional and they are divided
+into options and configurators.
+
+.. TODO: explain that recipe contents must be versioned


We should also explain the directory structure: vendor/package/version where version is the minimum version supported by the recipe

fabpot · 2017-04-11T14:53:13Z

README.rst

+
+This option defines one or more alternative names that can be used to install
+the dependency. Its value is an array of strings. For example, if a dependency
+is published as the ``acme-inc/acme-log-monolog-handler``, it can define one or


is published as ~~the~~

fabpot · 2017-04-11T14:54:07Z

README.rst

+        "aliases": ["acme-log", "acmelog"]
+    }
+
+Developers can now install this dependency as ``composer require acme-log``.


"as acme-log" or "with composer require acme-log"

fabpot · 2017-04-11T14:54:49Z

README.rst

+.. note::
+
+    When using ``version_aliases``, the directory where the recipe is defined
+    must be the oldest supported version (``3.3`` in the previous example).


Would be 3.2 here as you don't need to duplicate the version from the directory name. That's only additional versions.

fabpot · 2017-04-11T14:55:17Z

README.rst

+Enables one or more bundles in the Symfony application by appending them to the
+``bundles.php`` file. Its value is an associative array where the key is the
+bundle class name and the value is an array of environments where it must be
+enabled. The supported environtments are ``dev``, ``prod``, ``test`` and ``all``


environments <- typo

fabpot · 2017-04-11T14:56:00Z

README.rst

+        }
+    }
+
+The previous recipe is transformed by Symfony Flex into the following PHP code::


As this is a README, you need to be explicit about highlighting, so you cannot use ::, but .. code-block:: php instead.

fabpot · 2017-04-11T14:56:58Z

README.rst

+            "MAILER_HOST": "localhost",
+            "MAILER_PORT": "25",
+            "MAILER_USER": "",
+            "MAILER_PASSWORD": ""


Same as for the DB, we are now using MAILER_URL :)

fabpot · 2017-04-13T14:21:12Z

Thank you @javiereguiluz.

javiereguiluz added 2 commits April 5, 2017 11:17

Added an initial documentation for Symfony Flex recipes

d9e091d

Minor tweaks

78b32ec

fabpot force-pushed the master branch from dd9e279 to 6250f46 Compare April 7, 2017 18:29

javiereguiluz added 2 commits April 7, 2017 21:44

Improved docs explaining "aliases" and "version_aliases" options

d72b9dc

Fixed a JSON typo

3738ee6

fabpot reviewed Apr 7, 2017

View reviewed changes

README.rst Outdated

.. code-block:: json

{

"version_aliases": ["3.3", "3.4", "4.0-dev"]

Copy link

Member

fabpot Apr 7, 2017

Choose a reason for hiding this comment

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

should be "4.0".

fixed a version number

0475f2c

fabpot reviewed Apr 11, 2017

View reviewed changes

stof requested changes Apr 11, 2017

View reviewed changes

Fixed everything

c3a7a9c

fabpot reviewed Apr 11, 2017

View reviewed changes

fabpot approved these changes Apr 11, 2017

View reviewed changes

Another round of fixes

e634656

symfony-bot deployed to staging April 13, 2017 10:37 View deployment

Documented the directory structure of recipes

9529769

symfony-bot deployed to staging April 13, 2017 10:43 View deployment

fabpot closed this in 80e1aec Apr 13, 2017

Uh oh!

Added an initial documentation for Symfony Flex recipes #6

Added an initial documentation for Symfony Flex recipes #6

Uh oh!

Conversation

javiereguiluz commented Apr 5, 2017

Uh oh!

fabpot commented Apr 6, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fabpot commented Apr 13, 2017

Uh oh!

Uh oh!