From f1485147503d3b22b5f7a9db1b55310448bb7528 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 10 Oct 2014 18:59:41 +0200 Subject: [PATCH] add doc for developers --- source/development/create-a-new-bundle.rst | 30 +++ source/development/index.rst | 10 + source/development/installation.rst | 110 ++++++++++ source/development/installation.rst~ | 110 ++++++++++ source/development/make-test-working.rst | 231 +++++++++++++++++++++ source/index.rst | 21 +- source/installation/installation.rst | 21 ++ 7 files changed, 530 insertions(+), 3 deletions(-) create mode 100644 source/development/create-a-new-bundle.rst create mode 100644 source/development/index.rst create mode 100644 source/development/installation.rst create mode 100644 source/development/installation.rst~ create mode 100644 source/development/make-test-working.rst diff --git a/source/development/create-a-new-bundle.rst b/source/development/create-a-new-bundle.rst new file mode 100644 index 000000000..b1a581bd4 --- /dev/null +++ b/source/development/create-a-new-bundle.rst @@ -0,0 +1,30 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Create a new bundle +******************** + +Create your own bundle is not a trivial task. + +The easiest way to achieve this is seems to be : + +1. Prepare a fresh installation of the chill project, in a new directory +2. Create a new bundle in this project, in the src directory +3. Initialize a git repository **at the root bundle**, and create your initial commit. +4. Register the bundle with composer/packagist. If you do not plan to distribute your bundle with packagist, you may use a custom repository for achieve this [#f1]_ +5. Move to a development installation, made as described in the :ref:`installation-for-development` section, and add your new repository to the composer.json file +6. Work as :ref:`usual ` + +.. warning:: + + This part of the doc is not yet tested + +TODO + + +.. [#f1] Be aware that we use the Affero GPL Licence, which ensure that all users must have access to derivative works done with this software. diff --git a/source/development/index.rst b/source/development/index.rst new file mode 100644 index 000000000..c1ee46d17 --- /dev/null +++ b/source/development/index.rst @@ -0,0 +1,10 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Development +########### diff --git a/source/development/installation.rst b/source/development/installation.rst new file mode 100644 index 000000000..6c5783ebb --- /dev/null +++ b/source/development/installation.rst @@ -0,0 +1,110 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +.. _installation-for-development : + +Installation for development +**************************** + +Installation for development should let you able to have an access to the source code, upload the code to our CVS (i.e. `git`_), and working with `composer`_. + +As Chill is divided into modules, each module has his own repository. + +Installation and big picture +----------------------------- + +At first, you should install Chill as described in the :ref:`basic-installation` section. + +Two things must be modified : + +At first, You should add the `--prefer-source` argument when you create project. + +.. code-block:: bash + + php composer.phar create-project champs-libres/chill-standard \ + path/to/your/directory --stability=dev --prefer-source + +Secondly, if composer ask you the following question : :: + + Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? + +**You should answer `n` (no).** + +This will install a project. All downloaded modules will be stored in the `/vendor` directories. In those directories, you will have access to the git commands. + +.. code-block:: bash + + $ cd vendor/champs-libres/chill-main/ + $ git remote -v + composer git://github.com/Champs-Libres/ChillMain.git (fetch) + composer git://github.com/Champs-Libres/ChillMain.git (push) + origin git://github.com/Champs-Libres/ChillMain.git (fetch) + origin git@github.com:Champs-Libres/ChillMain.git (push) + +Working with your own fork +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + This section has not been tested yet. Feedback wanted. + +Ideally, you will work on a fork of the main github repository. To ensure that composer will download the code from **your** repository, you will have to adapt the `composer.json` file accordingly, using your own repository. + +Add the following lines to your composer.json file if you want to force composer to download from your own repository. This will force to use your own repository for the ChillMain bundle, insert in `composer.json` the following lines : + +.. code-block:: json + + "repositories": [ + { + "type": "git", + "url": "git://github.com/your-github-username/ChillMain.git" + } + ] + +You may also `use aliases `_ to define versions. + +.. _editing-code-and-commiting : + +Editing the code and commiting +------------------------------ + +You may edit code in the `vendor/path/to/the/bundle` directory. + +After your edits, you should commit as usually : + +.. code-block:: bash + + $ cd vendor/path/to/bundle + $ git status + Sur la branche master + Votre branche est à jour avec 'origin/master'. + + rien à valider, la copie de travail est propre + +.. warning + + The git command must be run from you vendor bundle's path (`vendor/path/to/bundle`). + +Tips +^^^^ + +The command `composer status` (`see composer documentation `_) will give you and idea of which bundle has been edited : + +.. code-block:: bash + + $ cd ./../../ #back to the root project directory + $ composer status + You have changes in the following dependencies: + /path/to/your/project/install/vendor/champs-libres/chill-main + Use --verbose (-v) to see modified files + + + + +.. _git: http://git-scm.org +.. _composer: https://getcomposer.org diff --git a/source/development/installation.rst~ b/source/development/installation.rst~ new file mode 100644 index 000000000..b7633a751 --- /dev/null +++ b/source/development/installation.rst~ @@ -0,0 +1,110 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +.. _installation-for-development : + +Installation for development +**************************** + +Installation for development should let you able to have an access to the source code, upload the code to our CVS (i.e. `git`_), and working with `composer`_. + +As Chill is divided into modules, each module has his own repository. + +Installation and big picture +----------------------------- + +At first, you should install Chill as described in the :ref:`basic-installation` section. + +Two things must be modified : + +At first, You should add the `--prefer-source` argument when you create project. + +.. code-block:: bash + + php composer.phar create-project champs-libres/chill-standard \ + path/to/your/directory --stability=dev --prefer-source + +Secondly, if composer ask you the following question : :: + + Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? + +**You should answer `n` (no).** + +This will install a project. All downloaded modules will be stored in the `/vendor` directories. In those directories, you will have access to the git commands. + +.. code-block:: bash + + $ cd vendor/champs-libres/chill-main/ + $ git remote -v + composer git://github.com/Champs-Libres/ChillMain.git (fetch) + composer git://github.com/Champs-Libres/ChillMain.git (push) + origin git://github.com/Champs-Libres/ChillMain.git (fetch) + origin git@github.com:Champs-Libres/ChillMain.git (push) + +Working with your own fork +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning + + This section has not been tested yet. Feedback wanted. + +Ideally, you will work on a fork of the main github repository. To ensure that composer will download the code from **your** repository, you will have to adapt the `composer.json` file accordingly, using your own repository. + +Add the following lines to your composer.json file if you want to force composer to download from your own repository. This will force to use your own repository for the ChillMain bundle, insert in `composer.json` the following lines : + +.. code-block:: json + + "repositories": [ + { + "type": "git", + "url": "git://github.com/your-github-username/ChillMain.git" + } + ] + +You may also `use aliases `_ to define versions. + +.. _editing-code-and-commiting : + +Editing the code and commiting +------------------------------ + +You may edit code in the `vendor/path/to/the/bundle` directory. + +After your edits, you should commit as usually : + +.. code-block:: bash + + $ cd vendor/path/to/bundle + $ git status + Sur la branche master + Votre branche est à jour avec 'origin/master'. + + rien à valider, la copie de travail est propre + +.. warning + + The git command must be run from you vendor bundle's path (`vendor/path/to/bundle`). + +Tips +^^^^ + +The command `composer status` (`see composer documentation `_) will give you and idea of which bundle has been edited : + +.. code-block:: bash + + $ cd ./../../ #back to the root project directory + $ composer status + You have changes in the following dependencies: + /path/to/your/project/install/vendor/champs-libres/chill-main + Use --verbose (-v) to see modified files + + + + +.. _git: http://git-scm.org +.. _composer: https://getcomposer.org diff --git a/source/development/make-test-working.rst b/source/development/make-test-working.rst new file mode 100644 index 000000000..dccdc736f --- /dev/null +++ b/source/development/make-test-working.rst @@ -0,0 +1,231 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Make tests working +****************** + +Unit and functional tests are important to ensure that bundle may be deployed securely. + +In reason of the Chill architecture, test should be runnable from the bundle's directory and works correctly: this will allow continuous integration tools to run tests automatically. + +.. note:: + + Integration tools (i.e. `travis-ci `_) works like this : + + * they clone the bundle repository in a virtual machine, using git + * they optionnaly run `composer` to download and install depedencies + * they optionnaly run other command to prepare a database, insert fixtures, ... + * they run test + +On the developer's machine test should be runnable with two or three commands **runned from the bundle directory** : + +.. code-block:: bash + + $ composer install --dev + $ // command to insert fixtures, ... + $ phpunit + +This chapter has been inspired by `this useful blog post <>`_. + +Bootstrap phpunit for a standalone bundle +========================================== + +Unit tests should run after achieving this step. + + +phpunit.xml +----------- + +A `phpunit.xml.dist` file should be present at the bundle root. + +.. code-block:: xml + + + + + + + + ./Tests + + + + + ./ + + ./Resources + ./Tests + ./vendor + + + + + + +bootstrap.php +-------------- + +A file `boostrap.php`, located in the `Tests` directory, will allow phpunit to resolve class autoloading : + +.. code-block:: php + + ` should be added like this, if your `AppKernel.php` file is located in `Tests/Fixtures/App` directory: + +.. code-block:: xml + + + + + + + ./Tests + + + + + ./ + + ./Resources + ./Tests + ./vendor + + + + + + + + + +AppKernel.php +------------- + +This file boostrap the app. It contains three functions. This is the file used in the ChillMain bundle : + +.. code-block:: php + + load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml'); + } + + /** + * @return string + */ + public function getCacheDir() + { + return sys_get_temp_dir().'/AcmeHelloBundle/cache'; + } + + /** + * @return string + */ + public function getLogDir() + { + return sys_get_temp_dir().'/AcmeHelloBundle/logs'; + } + } + +config_test.yml +--------------- + +There are only few parameters required for the config file. This is the config file for ChillMain : + +.. code-block:: yaml + + # config/config_test.yml + imports: + - { resource: config.yml } #here we import a config.yml file, this is not required + + framework: + test: ~ + session: + storage_id: session.storage.filesystem + +.. code-block:: yaml + + # config/config.yml + framework: + secret: Not very secret + router: { resource: "%kernel.root_dir%/config/routing.yml" } + form: true + csrf_protection: true + session: ~ + default_locale: fr + translator: { fallback: fr } + profiler: { only_exceptions: false } + templating: #required for assetic. Remove if not needed + engines: ['twig'] + +.. note:: + + You must adapt config.yml file according to your required bundle. Some options will be missing, other may be removed... + +.. note:: + + If you would like to tests different environments, with differents configuration, you could create differents config_XXX.yml files. + +routing.yml +------------ + +You should add there all routing information needed for your bundle. + +.. code-block: yaml + + chill_main_bundle: + resource: "@CLChillMainBundle/Resources/config/routing.yml" + +That's it. Tests should not pass. diff --git a/source/index.rst b/source/index.rst index ef060f4e2..680329685 100644 --- a/source/index.rst +++ b/source/index.rst @@ -3,6 +3,14 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + Welcome to Chill documentation! ===================================== @@ -16,7 +24,10 @@ Contents of this documentation: :maxdepth: 2 installation/installation.rst - + development/index.rst + development/installation.rst + development/create-a-new-bundle.rst + development/make-test-working.rst Contribute ========== @@ -30,7 +41,11 @@ Contribute Licence ======== -The project is available under the `GPLv3 licence`_. +The project is available under the `GNU AFFERO GENERAL PUBLIC LICENSE v3`_. + +This documentation is published under the `GNU Free Documentation License (FDL) v1.3`_ -.. _GPLv3 licence: http://www.gnu.org/licenses/gpl-3.0.txt +.. _GNU AFFERO GENERAL PUBLIC LICENSE v3: http://www.gnu.org/licenses/agpl-3.0.html +.. _GNU Free Documentation License (FDL) v1.3: http://www.gnu.org/licenses/fdl-1.3.html + diff --git a/source/installation/installation.rst b/source/installation/installation.rst index f67ef0fc4..518acf42f 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -1,10 +1,24 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + Installation ############ + +.. _basic-installation: + Basic installation `````````````````` + +Chill is written in PHP and use the `symfony framework`_. We take advantages of all the framework's feature, and installation should be as simple as installing symfony. + Requirements ------------ @@ -93,6 +107,12 @@ Composer will download `the standard architecture`_ and ask you a few question a You may accept the default parameters of `debug_toolbar`, `debug_redirects` and `use_assetic_controller` for a demonstration installation. For production, set them all to `false`. +If composer ask you the following question : :: + + Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? + +You may answer `Y` (Yes), or simply press the `return` button. + Launch your server ^^^^^^^^^^^^^^^^^^ @@ -110,3 +130,4 @@ Your server should now be available at `http://localhost:8000`. Type this addres .. _the standard architecture: https://github.com/Champs-Libres/chill-standard .. _composer: https://getcomposer.org .. _Firefox: https://www.mozilla.org +.. _symfony framework: http://symfony.com