From 93f92c7de831a94a18393ee1b27f9508b724809d Mon Sep 17 00:00:00 2001 From: Seonaid Date: Thu, 25 Mar 2021 16:53:59 -0300 Subject: [PATCH] Add CI templating for hugo docs and update documentation appropriately. --- docs/content/development/contribute.md | 9 +++++++++ docs/content/development/testing.md | 28 ++++++++++++++++++++++++++ docs/content/usage/hugo-docs.md | 4 +++- files/hugo-docs/.gitlab-ci.yml.tmpl | 6 ++++-- files/hugo-docs/config.yaml.tmpl | 6 ++++++ 5 files changed, 50 insertions(+), 3 deletions(-) create mode 100644 docs/content/development/testing.md diff --git a/docs/content/development/contribute.md b/docs/content/development/contribute.md index 3cfba7c..ef4f481 100644 --- a/docs/content/development/contribute.md +++ b/docs/content/development/contribute.md @@ -45,3 +45,12 @@ Drumkit is designed to gather all the necessary binaries for a particular projec At this point, you will be able to make changes to the files inside drumkit (below the `.mk` folder) and push them to the drumkit repo. However, most of the impacts of using Drumkit occur at the root directory, so there is an additional layer of abstraction to consider. + +#### Common points of failure + +When [testing](testing), for example, you need to remain aware of whether you are calling certain things (behat features, for example) from the project directory or from the `.mk` directory. Additionally, you need to keep the submodule and the project in sync. + +If you make changes to the `.mk` directory and then commit them in the containing project, you must push the `.mk` branch before pushing changes to the project, or the CI process is likely to fail, being unable to retrieve the correct commit of the Drumkit project. + + + diff --git a/docs/content/development/testing.md b/docs/content/development/testing.md new file mode 100644 index 0000000..1814c8c --- /dev/null +++ b/docs/content/development/testing.md @@ -0,0 +1,28 @@ +--- +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 (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. + +## 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/hugo-docs.md b/docs/content/usage/hugo-docs.md index 8501f99..cdbd653 100644 --- a/docs/content/usage/hugo-docs.md +++ b/docs/content/usage/hugo-docs.md @@ -33,4 +33,6 @@ 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//` + +To set up your Gitlab Pages, you need to update the configuration in `docs/config.yaml`, which is set to "http://mygroup.gitlab.io/myproject". diff --git a/files/hugo-docs/.gitlab-ci.yml.tmpl b/files/hugo-docs/.gitlab-ci.yml.tmpl index cf30877..c262618 100644 --- a/files/hugo-docs/.gitlab-ci.yml.tmpl +++ b/files/hugo-docs/.gitlab-ci.yml.tmpl @@ -22,10 +22,12 @@ pages: script: - make hugo - . d - - hugo + - mkdir public + - cd docs && hugo + - mv public .. artifacts: paths: - public only: - - master + - main diff --git a/files/hugo-docs/config.yaml.tmpl b/files/hugo-docs/config.yaml.tmpl index 73ccd91..e4866b9 100644 --- a/files/hugo-docs/config.yaml.tmpl +++ b/files/hugo-docs/config.yaml.tmpl @@ -1,6 +1,12 @@ # To configure this for deployment to gitlab pages, replace "mygroup" with your group name # and replace all instances of "myproject" with the name of the project. +# Note : You may be tempted to change "mygroup" and "myproject" to +# "" or "{{GITLAB_GROUP}}" in the template. *** Don't. *** +# There is a format checker at some point that breaks +# the entire process. I've forgotten exactly where. (SLD March 2021) + + baseUrl: "http://mygroup.gitlab.io/myproject/" languageCode: "en-US" defaultContentLanguage: "en"