From 59a5c1ba7b0e4dd7df06a120d648df07af682597 Mon Sep 17 00:00:00 2001 From: Francesco Sardara Date: Thu, 26 Sep 2019 18:44:59 +0200 Subject: [PATCH 1/5] OPENEUROPA-0000: Update README documentation. --- README.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index d91b801..d1b6461 100644 --- a/README.md +++ b/README.md @@ -20,21 +20,18 @@ You need to have the following software installed on your local development envi * [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). * [Docker Compose](https://docs.docker.com/compose/install/) +* PHP 7.1 or greater (only needed during project creation) ## Create the project The project is built using [Composer create-project](https://getcomposer.org/doc/03-cli.md#create-project). -This is the equivalent of doing a `git clone` followed by a `composer install`. -One does not need to be in this repository in order to use the `composer create-project` command. -The project can be created using the following command: +A new project can be created using the following command: ```bash composer create-project openeuropa/drupal-site-template --stability=dev --reference ``` -For local development, to test the Setup Wizard, run `composer setup` from the root of this project. - This will download the starterkit into the `--reference` folder and a wizard will ask you for the project name and your organisation. It will use this information to personalize your project's configuration files. @@ -44,38 +41,46 @@ takes several minutes. At the end you will be asked whether to remove the existing version history. It is recommended to confirm this question so that you can start your project with a clean slate. -After installing the dependencies, install a clean installation of your site, using the following command: +Now enter into the newly created site folder and start the Docker containers: ```bash -./vendor/bin/run toolkit:install-clean +cd "--reference" +docker-compose up -d ``` -Using default configuration, the development site files should be available in the `build` directory. +After all the containers have started (the time required can vary based on the host machine), +perform a clean installation of your site, using the following command: + +```bash +docker-compose exec web ./vendor/bin/run toolkit:install-clean +``` + +Using default configuration, the development site files should be available in the `web` directory. Before to commit your project on your repository, export the configuration on `config/sync` using the following command:. ```bash -./vendor/bin/drush cex +docker-compose exec web ./vendor/bin/drush cex ``` ## Drone A `.drone.yml` file is provided for running CI tests on Drone. Further details of how to set this up can be found in the [drone documentation](https://docs.drone.io/). - + ## Project management - -It is recommended that the version of `oe_theme` is locked to the current minor version before going live with the -project, so that updates to the theme do not cause problems to a running site. We recommend that this is periodically + +It is recommended that the version of `oe_theme` is locked to the current minor version before going live with the +project, so that updates to the theme do not cause problems to a running site. We recommend that this is periodically updated to the latest version, after doing manual testing. -A separate `.gitignore` file is provided which is used for the project. Drupal scaffold files should be committed after -running composer install or update. See the +A separate `.gitignore` file is provided which is used for the project. Drupal scaffold files should be committed after +running composer install or update. See the [Drupal scaffold documentation](https://github.com/drupal-composer/drupal-scaffold/blob/master/README.md#limitation) for further details. Further details of how to build sites, install Drupal and run tests can be found in the `README.md` found within your site - folder. + folder. Now you are ready to push your project to your chosen code hosting service. From c27a3c2982bc986301c035f43f6bd9583cc28def Mon Sep 17 00:00:00 2001 From: Antonio De Marco Date: Fri, 27 Sep 2019 11:03:14 +0200 Subject: [PATCH 2/5] OPENEUROPA-0000: Update generated README.md. --- README.md.dist | 157 +++++++++++++++++++++++-------------------------- 1 file changed, 72 insertions(+), 85 deletions(-) diff --git a/README.md.dist b/README.md.dist index b69d05c..fcdcb5b 100644 --- a/README.md.dist +++ b/README.md.dist @@ -1,85 +1,71 @@ # OpenEuropa Drupal project. -This project starter kit will create a website using the -OpenEuropa Drupal 8 platform. It will install the [OpenEuropa Profile](https://github.com/openeuropa/oe_profile) -which is a lightweight installation profile that includes the minimal number -of modules that are required to enable the [OpenEuropa Theme](https://github.com/openeuropa/oe_theme). -Using this theme will ensure that the project complies with the guidelines for -[European Component Library](https://github.com/ec-europa/europa-component-library). +This project starter kit will create a website using +[OpenEuropa components](https://github.com/openeuropa/documentation/blob/master/docs/openeuropa-components.md). +It will install only two components: + +- [The OpenEuropa Profile](https://github.com/openeuropa/oe_profile): + a lightweight Drupal installation profile that includes the minimal number of + modules to help get your started +- [The OpenEuropa Theme](https://github.com/openeuropa/oe_theme): the official + Drupal 8 theme of the European Commission which will ensure that the project + complies with the [European Component Library](https://github.com/ec-europa/europa-component-library) + guidelines. In order to build the functionality of the website you are free to use any of the [OpenEuropa components](https://github.com/openeuropa/openeuropa/blob/master/docs/openeuropa-components.md). -Starting a new project is a 4 step procedure: - -## 1. Prerequisites +## Prerequisites You need to have the following software installed on your local development environment: -* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). * [Docker Compose](https://docs.docker.com/compose/install/) -## 2. Configuration +Having the following installed locally is also recommended, but not mandatory: + +* PHP 7.1 or greater +* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). + +**Please be aware:** the OpenEuropa team will only address support requests +if you use the provided `docker-compose.yml`. -The project ships with default configuration that is intended to run the -website on the Docker containers we provide. If you are content with using -these, you can skip directly to step 3. +## Configuration -If you want to run the website using your locally installed LAMP stack, you -will want to change the configuration to match your local system. +The project ships with default setup configuration that is intended to run the +website on the Docker containers we provide. -Customize the default configuration values by copying `runner.yml.dist` to -`runner.yml`: +To customize the default configuration values copy `runner.yml.dist` to `runner.yml`: ```bash cp runner.yml.dist runner.yml ``` -Now edit `runner.yml` with your most beloved text editor. You will want to set -the database host to `localhost`, and provide the correct database name and -credentials. Also update the `base_url` and Selenium path to match your local -environment. - -## 3. Installation - -### 3.1. Using Docker - -You can build a development site using [Docker](https://www.docker.com/get-docker) and -[Docker Compose](https://docs.docker.com/compose/) with the provided configuration. - -Docker provides the necessary services and tools such as a web server and a database server to get the site running, -regardless of your local host configuration. +Now edit `runner.yml` with your most beloved text editor and change setup +configuration as needed. -#### Requirements: +## Site build and installation -- [Docker](https://www.docker.com/get-docker) -- [Docker Compose](https://docs.docker.com/compose/) +The shipped `docker-compose.yml` file provides the necessary services and tools +to install, run and test an OpenEuropa Drupal 8 site. -#### Configuration +By default, Docker Compose reads two files, a `docker-compose.yml` and an +optional `docker-compose.override.yml` file. By convention, the `docker-compose.yml` +contains your base configuration. The override file, as its name implies, +can contain configuration overrides for existing services or entirely new services. -By default, Docker Compose reads two files, a `docker-compose.yml` and an optional `docker-compose.override.yml` file. -By convention, the `docker-compose.yml` contains your base configuration and it's provided by default. -The override file, as its name implies, can contain configuration overrides for existing services or entirely new -services. If a service is defined in both files, Docker Compose merges the configurations. -Find more information on Docker Compose extension mechanism on [the official Docker Compose documentation](https://docs.docker.com/compose/extends/). - -#### Usage +Find more information on Docker Compose extension mechanism on +[the official Docker Compose documentation](https://docs.docker.com/compose/extends/). To start, run: -```bash -docker-compose up -``` - -It's advised to not daemonize `docker-compose` so you can turn it off (`CTRL+C`) quickly when you're done working. -However, if you'd like to daemonize it, you have to add the flag `-d`: - ```bash docker-compose up -d ``` +This will run the Docker containers in the background, i.e. it will "daemonize" them. + Then: ```bash @@ -87,51 +73,31 @@ docker-compose exec web composer install docker-compose exec web ./vendor/bin/run toolkit:install-clean ``` -Using default configuration, the development site files should be available in the `build` directory and the development site -should be available at: [http://127.0.0.1:8080/build](http://127.0.0.1:8080/build). +The site build will be available in the `web` directory and the site itself +will be reachable at: [http://localhost:8080/web](http://localhost:8080/web). -#### Running the tests +## Running the tests -To run the grumphp checks: +To run the coding standards and other static checks: ```bash docker-compose exec web ./vendor/bin/grumphp run ``` -To run the phpunit tests: - -```bash -docker-compose exec web ./vendor/bin/phpunit -``` - -To run the behat tests: +To run Behat tests: ```bash docker-compose exec web ./vendor/bin/behat ``` -### 3.2. Using a local LAMP stack - -Install the website using the task runner: - -```bash -./vendor/bin/run drupal:site-install -``` - -The site will be available through your local web server. - -To verify whether everything works as expected, you can run the example Behat -test suite: - -```bash -./vendor/bin/behat -``` - -## 4. Commit and push +## Commit and push -The final step is to create a new git repository and commit all the files. A +The final step is to have a new git repository and commit all the files. A `.gitignore` file is provided to ensure you only commit your own project files. +If you have not been already provided with one please contact your management +and/or the Quality Assurance team. + ```bash git init git add . @@ -140,10 +106,31 @@ git commit -m "Initial commit." Now you are ready to push your project to your chosen code hosting service. -## 4. CI on Drone +## Continuous integration and deployment + +To check the status of the continuous integration of your project, go to [Drone](https://drone.fpfis.eu/). + +A pipeline - created and maintained by DevOps - is applied by default. +It manages the code review of the code, it runs all tests on the repository and +builds the site artifact for the deployment. + +You can control which commands will be ran during deployment by creating +and pushing a `.opts.yml` file. + +If none is found the following one will be ran: + +```yml +upgrade_commands: + - './vendor/bin/drush state:set system.maintenance_mode 1 --input-format=integer -y' + - './vendor/bin/drush updatedb -y' + - './vendor/bin/drush cache:rebuild' + - './vendor/bin/drush state:set system.maintenance_mode 0 --input-format=integer -y' + - './vendor/bin/drush cache:rebuild' +``` -To check the status of the continuous integration of your project, go to [Drone] (https://drone.fpfis.eu/). +The following conventions apply: -A pipeline - created and maintained by devops - is applied by default. It manages the code review of the code, -runs all the business tests on the repository and builds the site artifact for the deployment. -Customizing this pipeline is possible by adding a custom ".drone.yml" file to the project's root folder. +- Every push on the site's deployment branch (usually `master`) will trigger + a deployment on the acceptance environment +- Every new tag on the site's deployment branch (usually `master`) will + trigger a deployment on production From 5656f0cc629ceadd2cf1f2023c62eee3a9d8a255 Mon Sep 17 00:00:00 2001 From: Antonio De Marco Date: Fri, 27 Sep 2019 11:34:16 +0200 Subject: [PATCH 3/5] OPENEUROPA-0000: Clarify project scope on main README.md. --- README.md | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index d1b6461..cbb8e6f 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,10 @@ -# OpenEuropa template for Drupal projects - -This is based on [drupal-composer/drupal-project](https://github.com/drupal-composer/drupal-project). +# OpenEuropa template for Drupal 8 projects [![Build Status](https://drone.fpfis.eu/api/badges/openeuropa/drupal-site-template/status.svg?branch=master)](https://drone.fpfis.eu/openeuropa/drupal-site-template) -This project template provides a starter kit for creating a website using the -OpenEuropa Drupal 8 platform. It will install the [OpenEuropa Profile](https://github.com/openeuropa/oe_profile) -which is a lightweight installation profile that includes the minimal number -of modules that are required to enable the [OpenEuropa Theme](https://github.com/openeuropa/oe_theme). -Using this theme will ensure that the project complies with the guidelines for -[European Component Library](https://github.com/ec-europa/europa-component-library). - -In order to build the functionality of the website you are free to use any of the -[OpenEuropa components](https://github.com/openeuropa/openeuropa/blob/master/docs/openeuropa-components.md). - -## Prerequisites +**Please note:** this repository contains code that is necessary to generate +a new Drupal 8 project, please read carefully the **Start a new project** +section below before proceeding. You need to have the following software installed on your local development environment: @@ -22,11 +12,9 @@ You need to have the following software installed on your local development envi * [Docker Compose](https://docs.docker.com/compose/install/) * PHP 7.1 or greater (only needed during project creation) -## Create the project - -The project is built using [Composer create-project](https://getcomposer.org/doc/03-cli.md#create-project). +## Start a new project -A new project can be created using the following command: +To create a new Drupal 8 project run the following command: ```bash composer create-project openeuropa/drupal-site-template --stability=dev --reference From 4839cfe0a723e21d4c6cd870372f4c966bbc03f6 Mon Sep 17 00:00:00 2001 From: Francesco Sardara Date: Fri, 27 Sep 2019 13:12:44 +0200 Subject: [PATCH 4/5] fix-documentation: Move site installation steps inside the project README instead of the main one. --- README.md | 26 +++----------------------- README.md.dist | 27 +++++++++++++++++---------- 2 files changed, 20 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index cbb8e6f..2320010 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Build Status](https://drone.fpfis.eu/api/badges/openeuropa/drupal-site-template/status.svg?branch=master)](https://drone.fpfis.eu/openeuropa/drupal-site-template) **Please note:** this repository contains code that is necessary to generate -a new Drupal 8 project, please read carefully the **Start a new project** +a new Drupal 8 project, please read carefully the [Start a new project](#start-a-new-project) section below before proceeding. You need to have the following software installed on your local development environment: @@ -29,28 +29,8 @@ takes several minutes. At the end you will be asked whether to remove the existing version history. It is recommended to confirm this question so that you can start your project with a clean slate. -Now enter into the newly created site folder and start the Docker containers: - -```bash -cd "--reference" -docker-compose up -d -``` - -After all the containers have started (the time required can vary based on the host machine), -perform a clean installation of your site, using the following command: - -```bash -docker-compose exec web ./vendor/bin/run toolkit:install-clean -``` - -Using default configuration, the development site files should be available in the `web` directory. - -Before to commit your project on your repository, export the configuration on `config/sync` -using the following command:. - -```bash -docker-compose exec web ./vendor/bin/drush cex -``` +The following steps to get your new site up and running can be found in the +README inside your newly created project folder. ## Drone diff --git a/README.md.dist b/README.md.dist index fcdcb5b..48ba5d1 100644 --- a/README.md.dist +++ b/README.md.dist @@ -76,18 +76,11 @@ docker-compose exec web ./vendor/bin/run toolkit:install-clean The site build will be available in the `web` directory and the site itself will be reachable at: [http://localhost:8080/web](http://localhost:8080/web). -## Running the tests - -To run the coding standards and other static checks: - -```bash -docker-compose exec web ./vendor/bin/grumphp run -``` - -To run Behat tests: +Before to commit your project on your repository, export the configuration on `config/sync` +using the following command: ```bash -docker-compose exec web ./vendor/bin/behat +docker-compose exec web ./vendor/bin/drush cex ``` ## Commit and push @@ -106,6 +99,20 @@ git commit -m "Initial commit." Now you are ready to push your project to your chosen code hosting service. +## Running the tests + +To run the coding standards and other static checks: + +```bash +docker-compose exec web ./vendor/bin/grumphp run +``` + +To run Behat tests: + +```bash +docker-compose exec web ./vendor/bin/behat +``` + ## Continuous integration and deployment To check the status of the continuous integration of your project, go to [Drone](https://drone.fpfis.eu/). From b863669ea0feb6dcb1ad60c3fa05b08d894ef17c Mon Sep 17 00:00:00 2001 From: Antonio De Marco Date: Fri, 27 Sep 2019 14:07:51 +0200 Subject: [PATCH 5/5] OPENEUROPA-0000: Remove outdated information about scaffolding and other outdated documentation. --- README.md | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 2320010..fd1cb84 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ section below before proceeding. You need to have the following software installed on your local development environment: -* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). +* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx) * [Docker Compose](https://docs.docker.com/compose/install/) * PHP 7.1 or greater (only needed during project creation) @@ -30,25 +30,4 @@ existing version history. It is recommended to confirm this question so that you can start your project with a clean slate. The following steps to get your new site up and running can be found in the -README inside your newly created project folder. - -## Drone - -A `.drone.yml` file is provided for running CI tests on Drone. Further details of how to set this up can be found in the - [drone documentation](https://docs.drone.io/). - -## Project management - -It is recommended that the version of `oe_theme` is locked to the current minor version before going live with the -project, so that updates to the theme do not cause problems to a running site. We recommend that this is periodically -updated to the latest version, after doing manual testing. - -A separate `.gitignore` file is provided which is used for the project. Drupal scaffold files should be committed after -running composer install or update. See the -[Drupal scaffold documentation](https://github.com/drupal-composer/drupal-scaffold/blob/master/README.md#limitation) -for further details. - -Further details of how to build sites, install Drupal and run tests can be found in the `README.md` found within your site - folder. - -Now you are ready to push your project to your chosen code hosting service. +`README.md` inside your newly created project folder.