From 882d2f40392cafc1074d03421b8ead5450e258c3 Mon Sep 17 00:00:00 2001 From: Seonaid Date: Wed, 30 Jun 2021 16:38:33 -0400 Subject: [PATCH] Update documentation to include structure of the file system. Also correct some of the testing info. --- content/_index.md | 0 docs/content/development/structure.md | 47 +++++++++++++++++++++++++++ docs/content/development/testing.md | 9 +++-- docs/content/structure/_index.md | 33 ------------------- docs/content/testing/_index.md | 16 --------- mk/projects/20_hugo-docs.mk | 2 +- 6 files changed, 52 insertions(+), 55 deletions(-) delete mode 100644 content/_index.md create mode 100644 docs/content/development/structure.md delete mode 100644 docs/content/structure/_index.md delete mode 100644 docs/content/testing/_index.md diff --git a/content/_index.md b/content/_index.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/content/development/structure.md b/docs/content/development/structure.md new file mode 100644 index 0000000..77dab41 --- /dev/null +++ b/docs/content/development/structure.md @@ -0,0 +1,47 @@ +--- +title: Structure of the Drumkit Project + +--- + + +Drumkit contains three kinds of make files in the `mk` directory: +[ note: we need to distinguish between `mk` and `.mk` in the documentation] +- Projects +- Tasks +- Tools + +## Projects + +You can use drumkit to initialize the following types of projects: +- Ansible (creates the following components) + - Inventory + - Groups + - Hosts +- Packer +- Drupal +- Hugo docs sites +- Aegir +- Openstack +- Aegir VPS + + +## Tasks + +The "tasks" category is for ongoing building and maintenance tasks that have been automated with drumkit. + +This includes: +- Running the docs server (`make docs-start` and `make docs-kill`) +- Managing git submodules +- Running drumkit tests (`make test-drumkit`) +- Running ansible playbooks + +## Tools + +This set of files is primarily for the installation of new tooling software. If it's a noun, it's probably in the "Tools" category. This is an evolving list, so check the `mk/tools` folder for the lastest options. + +Some examples include: +- Hugo +- Gitlab-runner +- Lando (only on Linux - must be installed manually for OSX) +- Packer +- Terraform diff --git a/docs/content/development/testing.md b/docs/content/development/testing.md index 81f05ab..f44ca7e 100644 --- a/docs/content/development/testing.md +++ b/docs/content/development/testing.md @@ -7,16 +7,15 @@ 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). +Any time you make changes to your local instance of `drumkit` you should run the tests at the drumkit level: +`make test-drumkit`. 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. +## Gitlab Runner + 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. diff --git a/docs/content/structure/_index.md b/docs/content/structure/_index.md deleted file mode 100644 index 067d71c..0000000 --- a/docs/content/structure/_index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Structure of the Drumkit Project -draft: true - ---- - - -Drumkit contains three kinds of make files in the `mk` directory: -[ note: we need to distinguish between `mk` and `.mk` in the documentation] -- Projects -- Tasks -- Tools - -## Projects - -You can use drumkit to [install/build/initialize] the following types of projects: -- Ansible (Which creates the following components) - - Inventory - - Groups - - Hosts -- Packer -- Drupal[8] [This is being refactored to just be called drupal without the 8] -- Hugo docs sites -- Aegir -- Openstack -- Aegir VPS [how is this different from Aegir?] - - -## Tasks - - - -## Tools \ No newline at end of file diff --git a/docs/content/testing/_index.md b/docs/content/testing/_index.md deleted file mode 100644 index e80b394..0000000 --- a/docs/content/testing/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Testing -weight: 30 -draft: true - ---- - -Drumkit includes a suite of behat tests for projects and tools. -[Behat](https://docs.behat.org/en/latest/) is a Behaviour Driven Development Framework for PHP. - -To install the test software, run `make behat` -To run the tests, run `behat` directly on the command line. - -[Seonaid: Are there any tests for the tasks? Should there be?] - -It also include the ability to test the CI process by spinning up a local instance of gitlab-runner. \ No newline at end of file diff --git a/mk/projects/20_hugo-docs.mk b/mk/projects/20_hugo-docs.mk index 43917b4..f082d69 100644 --- a/mk/projects/20_hugo-docs.mk +++ b/mk/projects/20_hugo-docs.mk @@ -1,6 +1,6 @@ .PHONY: init-project-hugo-docs hugo-ci-local -init-project-hugo-docs: docs docs/config.yaml docs/layouts/index.json docs/themes/learn docs/content/_index.md .gitlab-ci.yml ##@projects@hugo Initialize a hugo site +init-project-hugo-docs: docs docs/config.yaml docs/layouts/index.json docs/themes/learn docs/content/_index.md .gitlab-ci.yml ##@projects@hugo Create a new hugo docs site at the root level of the project @echo "Initializing Hugo Docs project." @git add docs @git commit -m "Initialize docs site."