From a2edd04ec1c12e1bcb25c64eff39ae517b1fb78f Mon Sep 17 00:00:00 2001 From: Seonaid Date: Thu, 11 Mar 2021 14:29:00 -0400 Subject: [PATCH 1/4] Update hugo documentation --- docs/content/development/mustache.md | 5 +++-- docs/content/development/self-docs.md | 2 +- docs/content/usage/hugo-docs.md | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/content/development/mustache.md b/docs/content/development/mustache.md index f93687e..19be22d 100644 --- a/docs/content/development/mustache.md +++ b/docs/content/development/mustache.md @@ -10,8 +10,9 @@ project codebases, etc. We are using the GoLang implementation of mustache because it is available as a self-contained binary for easy download. To use it in a project, you need to have installed -mustache by running `make mustache` first; in a Makefile, ensure you have listed it -as a dependency so it gets installed before you try to use it, e.g.: +mustache by running `make mustache` first. + +If you are using for templating in a Makefile, list it as a dependency so it gets installed before you try to use it, e.g.: ``` config.yml: mustache diff --git a/docs/content/development/self-docs.md b/docs/content/development/self-docs.md index 6d7be07..1eefd5f 100644 --- a/docs/content/development/self-docs.md +++ b/docs/content/development/self-docs.md @@ -4,7 +4,7 @@ weight: 50 draft: true --- -This text is coming from the docs folder inside the drumkit project. +This text (what you are reading right now) is coming from the `docs` folder inside the drumkit project. However, Drumkit also has a self-documentation feature built in to provide command line assistance for the most common tasks. diff --git a/docs/content/usage/hugo-docs.md b/docs/content/usage/hugo-docs.md index 8501f99..9c7e14f 100644 --- a/docs/content/usage/hugo-docs.md +++ b/docs/content/usage/hugo-docs.md @@ -33,4 +33,4 @@ The deployment to Gitlab Pages is managed automatically by the `.gitlab-ci.yml` At the bottom of the file, under `pages`, the `publish` stage will run `hugo` in the docs folder, which generates a set of static HTML files in the `public` folder, which is then made available through Gitlab pages. -The default address at Gitlab Pages will be \ No newline at end of file +The address at Gitlab Pages will be `http://.gitlab.io//` \ No newline at end of file From a6981f6719d04c0b6340a97b0a483d737a421b15 Mon Sep 17 00:00:00 2001 From: Seonaid Date: Tue, 16 Mar 2021 12:07:52 -0300 Subject: [PATCH 2/4] Add information on running behat tests locally. --- docs/content/development/_index.md | 2 +- docs/content/development/testing.md | 18 ++++++++++++++++++ mk/tasks/docs.mk | 4 ++-- 3 files changed, 21 insertions(+), 3 deletions(-) create mode 100644 docs/content/development/testing.md diff --git a/docs/content/development/_index.md b/docs/content/development/_index.md index d130f8d..43d703b 100644 --- a/docs/content/development/_index.md +++ b/docs/content/development/_index.md @@ -1,7 +1,6 @@ --- title: Development How-To's weight: 30 -draft: false --- @@ -14,3 +13,4 @@ TOPICS: * Making new kinds of projects * Documentation (see above maintaining-drumk.it) * [Contributing to Drumkit](contribute) +* [Testing](testing) diff --git a/docs/content/development/testing.md b/docs/content/development/testing.md new file mode 100644 index 0000000..31981b9 --- /dev/null +++ b/docs/content/development/testing.md @@ -0,0 +1,18 @@ +--- +title: Drumkit Testing +weight: 40 +--- + +Drumkit is developed using a BDD approach with behat as the testing (suite?) + +The tests are located in the `.mk/features` directory. + +To run the tests locally, you need to install behat in the project. + +Navigate to the root directory of the project (the one above `.mk`) and run `make init-behat` + +You can test the installation by running `behat` (it just checks for correct installation of behat). + +To run the tests specific to the component you are developing, navigate to `.mk` and run `behat {filename}` for the component. For example, to run the tests for the hugo project, run `behat features/projects/hugo-docs.feature` + +These are the tests most likely to break and fail when you push a change, so they should be run locally before pushing to the repo. The CI process runs the complete behat suite on all branches, so this is the quickest way to prevent pipeline failures. diff --git a/mk/tasks/docs.mk b/mk/tasks/docs.mk index 7927062..8db34b3 100644 --- a/mk/tasks/docs.mk +++ b/mk/tasks/docs.mk @@ -1,10 +1,10 @@ # Build and serve our docs site locally. -.PHONY: docs docs-kill +.PHONY: docs-start docs-kill HUGO_SERVE_CMD=hugo serve --noHTTPCache --quiet --disableFastRender -docs: ## Run Hugo server locally in the background (http://localhost:1313). +docs-start: ## Run Hugo server locally in the background (http://localhost:1313). cd docs && $(HUGO_SERVE_CMD) 2>&1 > /dev/null & #TODO add support to kill local server on a mac From acaf17913ded0364025423f8e3709485b673304c Mon Sep 17 00:00:00 2001 From: Seonaid Date: Fri, 19 Mar 2021 12:37:31 -0300 Subject: [PATCH 3/4] Update hugo testing instructions --- docs/content/usage/hugo-docs.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/content/usage/hugo-docs.md b/docs/content/usage/hugo-docs.md index 9c7e14f..ca7da42 100644 --- a/docs/content/usage/hugo-docs.md +++ b/docs/content/usage/hugo-docs.md @@ -27,6 +27,18 @@ The automatically generated starting point is in `docs/content/_index.md`. To pu For guidance on using hugo to layout your docs site, refer to [hugo documentation](https://gohugo.io/getting-started/usage/) +### Local testing + +Initialization of the hugo docs site with drumkit includes the addition of a `gitlab-ci.yml` file at the root of the project. + +This file is used by gitlab-runner to trigger the CI tests. + +**If you cloned using the development script, you will need to update the URL of the .mk submodule manually for these tests to run successfully.** + +Edit the submodule information in `.gitmodules` at the root of the containing project. Change the URL of .mk to: https://gitlab.com/consensus.enterprises/drumkit.git + + + ### Deployment The deployment to Gitlab Pages is managed automatically by the `.gitlab-ci.yml` file. From 3291111b91ae6d1e2fa469592315e32ea5f56b39 Mon Sep 17 00:00:00 2001 From: Seonaid Date: Thu, 24 Jun 2021 10:49:23 -0400 Subject: [PATCH 4/4] Update instructions for gitlab-runner. --- docs/content/development/testing.md | 25 +++++++++++++++++++++++- docs/content/usage/drupal.md | 4 ++-- features/projects/drupal-project.feature | 2 +- 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/content/development/testing.md b/docs/content/development/testing.md index 31981b9..4913567 100644 --- a/docs/content/development/testing.md +++ b/docs/content/development/testing.md @@ -15,4 +15,27 @@ You can test the installation by running `behat` (it just checks for correct ins To run the tests specific to the component you are developing, navigate to `.mk` and run `behat {filename}` for the component. For example, to run the tests for the hugo project, run `behat features/projects/hugo-docs.feature` -These are the tests most likely to break and fail when you push a change, so they should be run locally before pushing to the repo. The CI process runs the complete behat suite on all branches, so this is the quickest way to prevent pipeline failures. +These are the tests most likely to break and fail when you push a change, so they should be run locally before pushing to the repo. + +The CI process (when you push changes to the [drumkit project](https://gitlab.com/consensus.enterprises/drumkit) on gitlab) runs the complete `behat` suite on any branch, not just master. Running the tests locally before pushing changes is a relatively easy way to prevent pipeline failures. + +This is not to say that you won't have pipeline failures; it will just catch the ones that break any tests associated with the code you just wrote. + +**Important Note on Local Testing** + +Drumkit includes the ability to install `gitlab-runner` locally, which will run through the entire build in the `.gitlab-ci.yml` file. + +To run the pipeline on a *project* that you are developing: +- Install gitlab-runner using `make gitlab-runner` +- Run the section of the `.gitlab-ci.yml` using `gitlab-runner exec docker ` + +Some of the projects have a `ci-local` target (or a `-ci-local` target), but this feature is still in development. This will be updated as the solution is standardized. + +However, there is a limitation in `gitlab-runner`: You cannot navigate into the `.mk` directory and run the pipeline at that level, because it cannot parse the relative paths to the subdirectory, which must be used as the repo for the pipeline. [More info on the gitlab ticket - not ours to fix](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2054) + +## Testing the output from Drumkit + +The ultimate test of Drumkit is that it pushes working code to the (surrounding/containing) project you are working on with it. + +Process: +If you are developing Drumkit, per se, you should test and push the project as well as the drumkit code. This ensures that any modifications we make to (for example) `.gitlab-ci.yml` templates produces the correct files in the end. diff --git a/docs/content/usage/drupal.md b/docs/content/usage/drupal.md index d03f6dd..8b2f3d3 100644 --- a/docs/content/usage/drupal.md +++ b/docs/content/usage/drupal.md @@ -30,7 +30,7 @@ git init wget -O - https://drumk.it/installer | /bin/bash . d -make init-project-drupal8 +make init-project-drupal ``` This will prompt you for some information to populate your project: @@ -113,7 +113,7 @@ recent `make snapshot` was taken. By passing a name or short description to these targets, one can save and restore multiple snapshots at different states or stages of development. The [code providing this -feature](https://gitlab.com/consensus.enterprises/drumkit/-/blob/master/files/drupal8/50_backup.mk) +feature](https://gitlab.com/consensus.enterprises/drumkit/-/blob/master/files/drupal-project/50_backup.mk) largely manages these symlinks, creating and using them, as well as listing or removing them using `make ls-snaps`, `make rm-snap` and `make rm-all-snaps`. diff --git a/features/projects/drupal-project.feature b/features/projects/drupal-project.feature index eb7880c..39b0ffd 100644 --- a/features/projects/drupal-project.feature +++ b/features/projects/drupal-project.feature @@ -1,4 +1,4 @@ -@init @drupal8 @project +@init @drupal @project Feature: Initialize Drupal projects with Lando. In order to start a new Drupal project in a Lando environment As a Drupal Developer