From 997228fc6e9be3e1439c51dc37e99ee54c06e667 Mon Sep 17 00:00:00 2001 From: Matthew Grasmick Date: Tue, 9 Aug 2016 14:08:01 -0400 Subject: [PATCH 1/2] Adding blt extension docs. --- INSTALL.md | 2 +- index.md | 8 ++++++ mkdocs.yml | 1 + scripts/blt/convert-to-composer.sh | 6 ++++- template/.travis.yml | 5 ++-- template/readme/best-practices.md | 3 +-- template/readme/extending-blt.md | 39 +++++++++++++++++++++++++++ template/scripts/git-hooks/pre-commit | 3 +-- 8 files changed, 58 insertions(+), 9 deletions(-) create mode 100644 template/readme/extending-blt.md diff --git a/INSTALL.md b/INSTALL.md index 2b2288e0f..4a90427b4 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -133,4 +133,4 @@ Note that all common project tasks are executed through `blt`. For a full list o ## Next Steps -Now that your new project works locally, read through the new [README.md](https://github.com/acquia/blt/blob/8.x/template/README.md) file in your project to learn how to perform common project tasks and integrate with third party tools. +Now that your new project works locally, read through the new [README.md](https://github.com/acquia/blt/blob/8.x/template/README.md) file in your project to learn how to perform common project tasks and integrate with third party tools. \ No newline at end of file diff --git a/index.md b/index.md index eb9dbcb63..f27ab92fd 100644 --- a/index.md +++ b/index.md @@ -2,6 +2,14 @@ Welcome to the BLT documentation site! Please read through the [Quick Start Guide](https://github.com/acquia/blt/INSTALL.md) to get started, and then browse the rest of this project's documentation in the sidebar. +# Documentation structure + +BLT Documentation is broken into the following top-level segments: + +* Overview - Information about BLT +* Getting started - How to add BLT to your project +* Project documentation - Templated documentation that will be added to your BLTed project. + # Contributing to BLT Please feel free to edit any of the pages in this documentation via the 'Edit on GitHub' link at the top right. If you would like to help improve BLT, please file issues via the GitHub issue queue. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and instructions. diff --git a/mkdocs.yml b/mkdocs.yml index ad23284f9..29864f6f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,4 +37,5 @@ pages: - Release notes: 'scripts/release-notes/README.md' - Setting up continuous integration: 'template/readme/ci.md' - Open source contribution: 'template/readme/os-contribution.md' + - Extending / Overriding BLT: 'template/readme/extending-blt.md' - Contributing: 'CONTRIBUTING.md' diff --git a/scripts/blt/convert-to-composer.sh b/scripts/blt/convert-to-composer.sh index d0a3fb8df..c11b6918a 100755 --- a/scripts/blt/convert-to-composer.sh +++ b/scripts/blt/convert-to-composer.sh @@ -59,7 +59,11 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then echo "" echo "* Restart your terminal session to register your new blt alias." echo "* Review your codebase and commit the desired changes." - echo "* Integrate your custom Phing files by adding their file paths to project.yml under the 'imports' key." + echo "* If you have a custom Phing build file, you will likely need to update it and add it to project.yml under the 'import' key. See readme/extending-blt.md." + echo "* If you are not using Lightning, remove lightning-specific target-hooks from project.yml." + # .travis.yml + # hash salt in settings.php + # readme overrides else exit 1 diff --git a/template/.travis.yml b/template/.travis.yml index 11f59e7a4..159ede358 100644 --- a/template/.travis.yml +++ b/template/.travis.yml @@ -46,12 +46,11 @@ install: - composer validate --no-check-all --ansi - composer install - export PATH=$TRAVIS_BUILD_DIR/vendor/bin:$PATH - - drupal init --quiet + # Initialize drupal console default configuration. + - drupal init # Install proper version of node for front end tasks. - nvm install 4.4.1 - nvm use 4.4.1 - # Initialize drupal console default configuration. - - drupal init before_script: # Clear drush release history cache, to pick up new releases. diff --git a/template/readme/best-practices.md b/template/readme/best-practices.md index dfd3a0bd2..bec73d3d1 100644 --- a/template/readme/best-practices.md +++ b/template/readme/best-practices.md @@ -82,8 +82,7 @@ See the [Drupal 8 Cache API](https://www.drupal.org/developing/api/8/cache) docu ## Patching -All modifications to contributed code should be performed via a patch. For detailed information on how to patch projects, please see [../patches/README.md] -(../patches/README.md) +All modifications to contributed code should be performed via a patch. For detailed information on how to patch projects, please see [../patches/README.md](../patches/README.md) ## Views diff --git a/template/readme/extending-blt.md b/template/readme/extending-blt.md new file mode 100644 index 000000000..076717e5f --- /dev/null +++ b/template/readme/extending-blt.md @@ -0,0 +1,39 @@ +# Extending / Overriding BLT + +To add or override a Phing target, you may create a custom build file. You must specify the location of your custom build file using the `import` key to your project.yml file. + +## Adding a custom target + + + + + +## Overriding an existing target + +To override an existing target, just give it the same name as the default target provided by BLT. E.g., + + + + + + + + + +## Overriding a variable value: + +You can override the value of any Phing variable used by BLT by either: + +1. Adding the variable to your project.yml file: + + behat.tags: @mytags + +2. Specifying the variable value in your `blt` command using [Phing](https://www.phing.info/docs/stable/hlhtml/index.html#d5e792) argument syntax `-D[key]=[value]`, e.g., + + blt tests:behat -Dbehat.tags='@mytags' + +3. Using a custom build properties file rather than project.yml: + + blt tests:behat -propertyfile mycustomfile.yml -propertyfileoverride + + diff --git a/template/scripts/git-hooks/pre-commit b/template/scripts/git-hooks/pre-commit index 5f2ad9943..60f4db718 100755 --- a/template/scripts/git-hooks/pre-commit +++ b/template/scripts/git-hooks/pre-commit @@ -12,6 +12,5 @@ if [ ! -f $PHPCS_BIN ]; echo "Sniffing staged files via PHP Code Sniffer." fi - -${ROOT_DIR}blt.sh validate:phpcs:files -Dfiles="$LIST" -q +${ROOT_DIR}/vendor/bin/blt validate:phpcs:files -Dfiles="$LIST" -q exit 0; From 3e36f991ed78778529bfddb315cca56cacfea33f Mon Sep 17 00:00:00 2001 From: Matthew Grasmick Date: Tue, 9 Aug 2016 14:51:38 -0400 Subject: [PATCH 2/2] Removing docs from template. --- INSTALL.md | 10 +++++----- README.md | 4 ++-- {template/readme => docs}/acsf-setup.md | 0 {template/readme => docs}/architecture.md | 0 {template/readme => docs}/best-practices.md | 0 {template/readme => docs}/ci.md | 0 {template/readme => docs}/code-review.md | 0 {template/readme => docs}/deploy.md | 0 {template/readme => docs}/dev-workflow.md | 0 {template/readme => docs}/examples/readme.md | 0 {template/readme => docs}/extending-blt.md | 0 {template/readme => docs}/features-workflow.md | 0 {template/readme => docs}/local-development.md | 0 {template/readme => docs}/onboarding.md | 0 {template/readme => docs}/os-contribution.md | 0 {template/readme => docs}/project-tasks.md | 0 {template/readme => docs}/release-process.md | 0 {template/readme => docs}/repo-architecture.md | 0 {template/readme => docs}/views.md | 0 index.md | 10 +--------- phing/tasks/blt.xml | 1 + scripts/blt/convert-to-composer.sh | 14 ++++++++++++++ template/README.md | 16 ---------------- tests/phpunit/BltTest.php | 4 ---- 24 files changed, 23 insertions(+), 36 deletions(-) rename {template/readme => docs}/acsf-setup.md (100%) rename {template/readme => docs}/architecture.md (100%) rename {template/readme => docs}/best-practices.md (100%) rename {template/readme => docs}/ci.md (100%) rename {template/readme => docs}/code-review.md (100%) rename {template/readme => docs}/deploy.md (100%) rename {template/readme => docs}/dev-workflow.md (100%) rename {template/readme => docs}/examples/readme.md (100%) rename {template/readme => docs}/extending-blt.md (100%) rename {template/readme => docs}/features-workflow.md (100%) rename {template/readme => docs}/local-development.md (100%) rename {template/readme => docs}/onboarding.md (100%) rename {template/readme => docs}/os-contribution.md (100%) rename {template/readme => docs}/project-tasks.md (100%) rename {template/readme => docs}/release-process.md (100%) rename {template/readme => docs}/repo-architecture.md (100%) rename {template/readme => docs}/views.md (100%) diff --git a/INSTALL.md b/INSTALL.md index 4a90427b4..43c90271d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -107,11 +107,11 @@ Note that all of the steps from this point forward are the same steps that would Before building your project dependencies and installing Drupal, you must have a fully functional \*AMP stack on your local machine. BLT intentionally does not provide this local development environment--that is outside of the scope of BLT’s intended responsibilities. It does, however, make recommendations for which tools you should use to manage your stack. -Please see [Local Development](template/readme/local-development.md) for more information on setting up your \*AMP stack: +Please see [Local Development](docs/local-development.md) for more information on setting up your \*AMP stack: -* [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects) -* [Drupal VM](template/readme/local-development.md#using-drupal-vm-for-blt-generated-projects) -* [Other](https://github.com/acquia/blt/blob/8.x/template/readme/local-development.md#alternative-local-development-environments) +* [Acquia Dev Desktop](docs/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects) +* [Drupal VM](docs/local-development.md#using-drupal-vm-for-blt-generated-projects) +* [Other](https://github.com/acquia/blt/blob/8.x/docs/local-development.md#alternative-local-development-environments) When you have completed setting up your local \*AMP stack, double check that the following pieces of information are still correct: @@ -133,4 +133,4 @@ Note that all common project tasks are executed through `blt`. For a full list o ## Next Steps -Now that your new project works locally, read through the new [README.md](https://github.com/acquia/blt/blob/8.x/template/README.md) file in your project to learn how to perform common project tasks and integrate with third party tools. \ No newline at end of file +Now that your new project works locally, read through the new [README.md](https://github.com/acquia/blt/blob/8.x/template/README.md) file in your project to learn how to perform common project tasks and integrate with third party tools. diff --git a/README.md b/README.md index 5998ffa27..996440e28 100644 --- a/README.md +++ b/README.md @@ -43,12 +43,12 @@ It scope is discretely defined. It is *not* intended to provide: * [Testing Framework](template/tests). * Behat: default `local.yml` configuration, example tests, `FeatureContext.php` * PHPUnit: default tests for ensuring proper functioning of BLT provided components -* [Project tasks](template/readme/project-tasks.md) +* [Project tasks](docs/project-tasks.md) * Executing tests and validating code * Building dependencies * (Re)installation of Drupal * Production-safe artifact generation and deployment -* [Continuous Integration](template/readme/ci.md) +* [Continuous Integration](docs/ci.md) * Travis CI * GitHub diff --git a/template/readme/acsf-setup.md b/docs/acsf-setup.md similarity index 100% rename from template/readme/acsf-setup.md rename to docs/acsf-setup.md diff --git a/template/readme/architecture.md b/docs/architecture.md similarity index 100% rename from template/readme/architecture.md rename to docs/architecture.md diff --git a/template/readme/best-practices.md b/docs/best-practices.md similarity index 100% rename from template/readme/best-practices.md rename to docs/best-practices.md diff --git a/template/readme/ci.md b/docs/ci.md similarity index 100% rename from template/readme/ci.md rename to docs/ci.md diff --git a/template/readme/code-review.md b/docs/code-review.md similarity index 100% rename from template/readme/code-review.md rename to docs/code-review.md diff --git a/template/readme/deploy.md b/docs/deploy.md similarity index 100% rename from template/readme/deploy.md rename to docs/deploy.md diff --git a/template/readme/dev-workflow.md b/docs/dev-workflow.md similarity index 100% rename from template/readme/dev-workflow.md rename to docs/dev-workflow.md diff --git a/template/readme/examples/readme.md b/docs/examples/readme.md similarity index 100% rename from template/readme/examples/readme.md rename to docs/examples/readme.md diff --git a/template/readme/extending-blt.md b/docs/extending-blt.md similarity index 100% rename from template/readme/extending-blt.md rename to docs/extending-blt.md diff --git a/template/readme/features-workflow.md b/docs/features-workflow.md similarity index 100% rename from template/readme/features-workflow.md rename to docs/features-workflow.md diff --git a/template/readme/local-development.md b/docs/local-development.md similarity index 100% rename from template/readme/local-development.md rename to docs/local-development.md diff --git a/template/readme/onboarding.md b/docs/onboarding.md similarity index 100% rename from template/readme/onboarding.md rename to docs/onboarding.md diff --git a/template/readme/os-contribution.md b/docs/os-contribution.md similarity index 100% rename from template/readme/os-contribution.md rename to docs/os-contribution.md diff --git a/template/readme/project-tasks.md b/docs/project-tasks.md similarity index 100% rename from template/readme/project-tasks.md rename to docs/project-tasks.md diff --git a/template/readme/release-process.md b/docs/release-process.md similarity index 100% rename from template/readme/release-process.md rename to docs/release-process.md diff --git a/template/readme/repo-architecture.md b/docs/repo-architecture.md similarity index 100% rename from template/readme/repo-architecture.md rename to docs/repo-architecture.md diff --git a/template/readme/views.md b/docs/views.md similarity index 100% rename from template/readme/views.md rename to docs/views.md diff --git a/index.md b/index.md index f27ab92fd..53d71db33 100644 --- a/index.md +++ b/index.md @@ -1,15 +1,7 @@ [Acquia BLT (Build and Launch Tool)](https://github.com/acquia/blt) generates new Drupal projects using a standardized template derived from Acquia Professional Services' best practices. Welcome to the BLT documentation site! Please read through the [Quick Start Guide](https://github.com/acquia/blt/INSTALL.md) to get started, and then browse the rest of this project's documentation in the sidebar. - -# Documentation structure - -BLT Documentation is broken into the following top-level segments: - -* Overview - Information about BLT -* Getting started - How to add BLT to your project -* Project documentation - Templated documentation that will be added to your BLTed project. # Contributing to BLT - + Please feel free to edit any of the pages in this documentation via the 'Edit on GitHub' link at the top right. If you would like to help improve BLT, please file issues via the GitHub issue queue. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and instructions. diff --git a/phing/tasks/blt.xml b/phing/tasks/blt.xml index a35840550..6d2e90e29 100644 --- a/phing/tasks/blt.xml +++ b/phing/tasks/blt.xml @@ -22,6 +22,7 @@ + diff --git a/scripts/blt/convert-to-composer.sh b/scripts/blt/convert-to-composer.sh index c11b6918a..cea10ac38 100755 --- a/scripts/blt/convert-to-composer.sh +++ b/scripts/blt/convert-to-composer.sh @@ -48,6 +48,20 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then echo "Removing deprecated BLT files from project." rm -rf build blt.sh tests/phpunit/blt + # Removing old docs. + rm acsf-setup.md + rm architecture.md + rm best-practices.md + rm deploy.md + rm dev-workflow.md + rm features-workflow.md + rm local-development.md + rm onboarding.md + rm project-tasks.md + rm release-process.md + rm repo-architecture.md + rm views.md + # Install (new) alias echo "Installing blt alias" yes | ./vendor/acquia/blt/blt.sh install-alias diff --git a/template/README.md b/template/README.md index 289aeb67c..4acfe2cec 100644 --- a/template/README.md +++ b/template/README.md @@ -2,22 +2,6 @@ Replace this with a brief description of the ${project.human_name} project. -Documentation by role: - -* Developer - * [Onboarding](readme/onboarding.md): “how do I get up and running on project work?” - * [Repository architecture](readme/repo-architecture.md): “how is the code organized, and why?” - * [Running project tasks](readme/project-tasks.md): “how do I _____ on my local machine?” - * [Best practices](readme/best-practices.md): "how should I write code?" - * [Workflow](readme/dev-workflow.md): “how do I contribute my code to this project?” - * [Automated testing](tests/README.md): “how do I write / run them, and why should I care?” -* Technical Architect - * [Project Architecture document](readme/architecture.md) - * [Deploying to cloud](readme/deploy.md) - * [Release process](readme/release-process.md) - * [Setting up continuous integration](readme/ci.md) - * [Open source contribution](readme/os-contribution.md) - ## Resources * JIRA - link me! diff --git a/tests/phpunit/BltTest.php b/tests/phpunit/BltTest.php index b07d6920f..a74e753da 100644 --- a/tests/phpunit/BltTest.php +++ b/tests/phpunit/BltTest.php @@ -39,10 +39,6 @@ public function testBltCreate() { '${project.machine_name}', file_get_contents($this->newProjectDir . '/docroot/sites/default/settings.php') ); - $this->assertNotContains( - '${project.human_name}', - file_get_contents($this->newProjectDir . '/readme/architecture.md') - ); } }