power_stencil 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1387471841811025d2ebdc21c23aec26f9341193
-  data.tar.gz: ff9722780a689f245baa21c3dbf5b5bef0a1024d
+  metadata.gz: b07abdd0e20d4fbcb3fa6101b2f51b6979dd0004
+  data.tar.gz: 568e506add9ea1c13cd6edb4a8b6d146d60ac593
 SHA512:
-  metadata.gz: df95d43e7e99fd25fe57bbb3713fc5707b53a2f939c9734720cbcd9bca4f7d8dfaff61294db2e8e245b768ff93c737aa1b6e14da9f64cb7fe07f234f8061ec16
-  data.tar.gz: 24ba3ea0b87f0dd480250b5a4b32e6c8e1730396d6e0b43820f10d97bb1084f405df74a3fd9dcfec7aa96a813014427163aebbf1e15a112b9d72bf9f9188b45a
+  metadata.gz: feea8307da3b4cd3c0851f9004aeefba5f20d4130f2da0a9cb1b8fa3c06e988bb936b6e513c15aa6928f7a23f44ff563aab1aa7a08b37d8ff47a9e4ef066abad
+  data.tar.gz: 87c4358e744a2aa22b96c475461ce996c4a82a2d73fb3b90b4560d12d62a6b5068611d9a4318b6c67891a7f5a322bda59dd5343af32753fdbd7b52f0b5b57a9b

data/README.md

@@ -5,7 +5,7 @@ PowerStencil
 
 <!-- TOC -->
 
-- [Core concepts](#core-concepts)
+- [Overview](#overview)
 - [Pfff, yet another templating engine...](#pfff-yet-another-templating-engine)
 - [Installation](#installation)
 - [Usage](#usage)
@@ -19,30 +19,28 @@ PowerStencil
 
 <!-- /TOC -->
 
-# Core concepts
+# Overview
 
 `PowerStencil` proposes a radical approach on how to manage your shared configuration.
 
-Internally `PowerStencil` is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization:
+Configuration is one of the most complex things to maintain, and anyone who participated in a large scale piece of software or documentation knows how complex it is to maintain, keep consistent and avoid duplication on the long run across the various projects that may share this configuration.
 
-![simple-flow-image]
+From a very high level point of view, the workfow `PowerStencil` proposes looks like:
 
-Configuration is one of the most complex things to maintain, and anyone who participated in a large scale piece of software or documentation knows how complex it is to maintain, keep consistent and avoid duplication on the long run across the various projects that may share this configuration.
+![simple-flow-image]
 
 `PowerStencil` provides **development and operations friendly workflows to fully manage the maintenance of a complex shared config** in order to generate anything you may want like _documentation_, _static sites_, _code_, _configuration_ for multiple tools..., while **avoiding duplication, and manage it like code** !
 
-It is a common pattern to introduce a database to manage this configuration, and it is a very bad idea because it implies extra tooling, and specific developments that de-facto become single point of failure at the heart of your development process. Why would you do that when something as versatile and ubiquitous as Git exists that will __integrate smoothly within your existing development and operations workflows__, builds, CI/CD, while benefiting from all the goodness provided by Git, like branches, decentralization, versioning, tags, code reviews, traceability, simplified fallbacks etc... ?
+It is a common pattern to introduce a database to manage shared configuration for CI/CD processes, and it is a very bad idea (see [F.A.Q.]) because it implies extra tooling, and specific developments that de-facto become single point of failure at the heart of your development process. Why would you do that when something as versatile and ubiquitous as Git exists that will integrate smoothly within your existing development and operations workflows, builds, CI/CD processes, while benefiting from all the goodness provided by Git, like branches, decentralization, versioning, tags, code reviews, traceability, simplified fallbacks etc... ?
 
-**With `PowerStencil` everything is maintained in a git repository**: data, templates, specific code. No more config loss, no more change applied without a full lineage.
-
-See some real world [example use cases].
+A `PowerStencil` project is composed of a data repository and a pretty standard templating flow to generate whatever is needed by your project or organization and **with `PowerStencil` everything is maintained in a git repository**: data, templates, specific code **without sacrificing on data integrity and relational features**. No more config loss, no more change applied without a full lineage.
 
 The `PowerStencil` gem provides the `power_stencil` executable which is a pluggable CLI to:
 
-- CRUD [entities] using either an editor or a dedicated REPL
-- Manage [templates]
-- Manage [builds]
-- Create and manipulate [plugins]
+- Manage the project data
+- Manage templates
+- Manage builds
+- Create and manipulate plugins
 
 # Pfff, yet another templating engine...
 
@@ -110,17 +108,19 @@ The program uses the standard paradigm of sub-commands (à-la-git), and each can
 
 To create a new project, use the `init` sub-command. It works as you would expect. If you run it in an existing directory it will create the project here but you can specify the directory where you want the project to be created (the path will be created provided you have the rights on the filesystem):
 
-    $ power_stencil init --project-path /where/you/want
+    $ power_stencil init /where/you/want/your/project
 
-The `--project-path` option can be applied to any sub-command, but à-la-git, once the project created if you are anywhere within the project tree, you don't need to specify the project path.
+Once the project created, if you are anywhere within the project tree, you don't need to specify the project path anymore (if needed, any `power_stencil` sub-command supports a `--project-path` option). If you're used to the Git command line, it works the same way, and you should not feel in uncharted territory...
 
 :information_source: The rest of this documentation will assume you are at the root of this created project.
 
-:information_source: Of course, once you created a new project you should version it with Git:
+**:information_source: Of course, once you've been creating a new project, you should version it with Git:**
 
     $ git init
+    $ git add .
     $ git commit -a -m 'Initial commit'
 
+This will allow you to track any change resulting of your interactions with `power_stencil` command line.
 
 ## `PowerStencil` project structure
 
@@ -141,9 +141,9 @@ The structure of a brand new `PowerStencil` project is the following:
     │   └── README.md
     └── versioned-config.yaml
 ```
-New directories will appear once you start some [builds] or when you will define [templates].
+New directories will appear once you start some [builds] or when you will define [templates], but this is the initial state.
 
-Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project.
+Not all the files in this directory should be versioned, and this the reason why there is a preconfigured `.gitignore` at the root of the project. It is prefilled so that unless you want to specifically avoid a file to be versioned, you don't need any action regarding `PowerStencil` project files.
 
 The project has two distinct config files. Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest will be versioned. But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml` which is not be versioned. The content defined in the latter overrides the content of the official one. This is a clean way for anyone who wants to test something to safely do it locally without the risk to pollute the central repo.
 
@@ -155,19 +155,25 @@ The `plugins` directory can optionally contain project specific plugins. Plugins
 
 The core of the system is the `entity`, so you should start by having a look at what entities are, how they are easily managed using the `PowerStencil` CLI and shell.
 
-:arrow_forward: [Entities]
+> :arrow_forward: [Entities]
 
 Then it is important to understand how to use entities within `templates`. Templates are the way to generate something (doc, code, descriptors, sites, whatever...) from the data that the entities represent.
 
-:arrow_forward: [Templates]
+> :arrow_forward: [Templates]
 
 The mechanism that combines entities and templates is called a `build`. A build is always attached to an entity (you build something). The result of a build is a set of files. Optionally an action can be triggered after the files are generated (could be as simple as calling a script that has been generated).
 
-:arrow_forward: [Builds]
+> :arrow_forward: [Builds]
 
 `PowerStencil` could stop there, and you would be able to do whatever you want, but there is a whole world beyond. `Plugins` provide a way to completely extend `PowerStencil`, further control relations between entities, implement complex post-build actions, add CLI sub-commands and options. Plugins can be local to the project or coming in the form of standard Ruby Gems ! The icing on the cake...
 
-:arrow_forward: [Plugins]
+> :arrow_forward: [Plugins]
+
+And course, you may:
+
+- Read the [F.A.Q.]
+- See some real world [example use cases].
+
 
 # Contributing
 
@@ -189,6 +195,7 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [builds]: doc/builds.md "Builds in PowerStencil"
 [plugins]: doc/plugins.md "Plugins in PowerStencil"
 [example use cases]: doc/example_use_cases.md "Example uses cases using PowerStencil"
+[F.A.Q.]: doc/faq.md "PowerStencil F.A.Q."
 [code of conduct]: CODE_OF_CONDUCT.md
 
 <!-- Code links -->

data/doc/builds.md

@@ -255,7 +255,7 @@ If you want to do something more custom after the build process completed, this
 [entities]: entities.md "Entities in PowerStencil"
 [templates]: templates.md "Templates in PowerStencil"
 [plugins]: plugins.md "Plugins in PowerStencil"
-[buildable]: entities.md#buildable--buildable_by "How to make an entity buildable ?"
+[buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?"
 [local entities]: entities.md#local-unversioned-entities "Local unversioned entities"
 
 <!-- Code links -->

data/doc/entities.md

@@ -33,7 +33,7 @@ Entities
         - [not_empty](#not_empty)
         - [should_match](#should_match)
         - [class_name](#class_name)
-        - [buildable / buildable_by](#buildable--buildable_by)
+        - [buildable and buildable_by](#buildable-and-buildable_by)
     - [Module you could include in your entity types](#module-you-could-include-in-your-entity-types)
     - [Adding functional code](#adding-functional-code)
 
@@ -908,7 +908,7 @@ PowerStencil DSL> e.valid? raise_error: true
 
 :warning: Use this one with caution, as it does not test anything regarding inheritance...
 
-### buildable / buildable_by
+### buildable and buildable_by
 
 One of the most important directives !
 More information is provided in the [builds] documentation, but basically this defines an `entity_type` as a potential target for the build process.

data/doc/faq.md

@@ -0,0 +1,106 @@
+F.A.Q.
+======
+
+<!-- TOC -->
+
+- [How does `PowerStencil` compare with a CMDB ?](#how-does-powerstencil-compare-with-a-cmdb-)
+- [Why is a "real" database a bad idea as configuration store for CI/CD ?](#why-is-a-real-database-a-bad-idea-as-configuration-store-for-cicd-)
+- [How does `PowerStencil` compare to environment variables + subst ?](#how-does-powerstencil-compare-to-environment-variables--subst-)
+- [Why data persisted in YAML ?](#why-data-persisted-in-yaml-)
+- [What are the system requirements ?](#what-are-the-system-requirements-)
+- [What is the status of `PowerStencil` ?](#what-is-the-status-of-powerstencil-)
+
+<!-- /TOC -->
+[:back:][Documentation root]
+
+# How does `PowerStencil` compare with a CMDB ?
+
+It could sound like a strange question. `PowerStencil` is absolutelly not designed with ITIL in mind but in the end its true that its data management part looks a lot like a [CMDB].
+
+- [Entities][entities] (and more specifically entity types) can cover most aspects (I am not ITIL expert enough to say it covers all of them) of ITIL's _Configuration Items_. Default entities provided with `PowerStencil` do not contain all necessary attributes to do be really considered as _configuration items_, but it should be very easy to achieve with custom entities. In fact it could be a good idea of [plugin][plugins]...
+- Relation semantics in `PowerStencil` cover 1-1, 1-n and composition relation patterns.
+- Versioning is achieved through Git. Implying on top of versioning, branching, merging
+
+But `PowerStencil` cannot be simplified to it's "database" aspect. It goes well beyond, and is as well a pragmatic workflow for developers and operations to actually do something out of this data. A [CMDB] may be used by external processes in order to achieve what `PowerStencil` does out of the box.
+
+
+# Why is a "real" database a bad idea as configuration store for CI/CD ?
+
+There are some reasons why using a database in the scope of CI/CD is not a good idea.
+
+Basically the CI/CD infrastructure could be built around Jenkins, containerized tools (Drone for example), Travis, GitlabCI... The goal being to provide the **easiest possible way for the developer** to perform integration tests and eventually build and deploy software.
+
+But the easiest possible way for the developer doesn't mean that the underlying infrastructure is simple to put in place or maintain. In fact it is not !
+
+Anything you add to this carefully crafted mechanic could turn into an infrastructure management nightmare. And a database (and its availability, maintenance) is clearly not the simplest component to inject in your infrastructure...
+
+On top of this, a database does not not provide by default all the required features. Versioning is obviously one of them but of course not the only one (you may think about branching or others...). Meaning that **you need to have custom developments** on top of the chosen database in order to achieve all the required features. It immediately becomes a de-facto single point of failure in your CI/CD process...
+
+Relying on Git to achieve the storage, versioning, branching, decentralization is a much easier way to achieve the same. There is no need to have specific developments as any CI/CD mechanism knows how to deal with extra git repository.
+
+# How does `PowerStencil` compare to environment variables + subst ?
+
+If you have very few files/templates, you may consider this as a solution, but as soon as your templates will complexify or some data need to reference some other, you will enter a loop of death that will make you regret your initial choice.
+
+`PowerStencil` is not a templating engine, it is a framework! 
+
+Not only it [allows structured and relational data][entities], it structures your work as well, and provides mechanisms to allow developers to [easily perform tests without committing unwanted changes by mistake][overrides].
+
+Due on how it is easy to use `PowerStencil`, even for the simplest use cases, there is no real reason not to use it.
+
+
+# Why data persisted in YAML ?
+
+Assuming Git is used for storage and versioning **we need to have a data format that is git-friendly**.
+
+- So it discards local databases like SQLite, BerkeleyDB or others which are binary formats.
+- XML is **not** a human readable format and is a real pain to _diff_. It should have been kept for what it has been designed for, ie machine to machine protocols...
+
+So the two main remaining contenders are JSON and YAML. Although there is no real reason to take one more than the other, including the manipulating language, would I have written `PowerStencil` in JS or Go, I may probably have chosen JSON as storage format. But it is written in Ruby and therefore I went for YAML.
+
+
+# What are the system requirements ?
+
+`PowerStencil` has been developed under Linux, but it's only requiring a working Ruby installed on your machine. 
+
+As such, even if I never tested, I would expect it to probably work out of the box on MacOS, BSD or other Unices supporting Ruby 2.2+.
+
+Regarding Windows, I stopped using spywareOS years ago so I can't really tell you. Last time I tried using Ruby on Windows (maybe 10 years ago), I did face a lot of dependency issues. Maybe things are better now, but I have no idea. As far as I understood you can now have an Ubuntu running on top of Windows 10 as a kind of blessed VM. I would probably more go this way...
+
+
+# What is the status of `PowerStencil` ?
+
+Although `PowerStencil` is still under development, **it can already be safely used**.
+
+Regarding `PowerStencil` core:
+
+- The part that may evolve the most is the plugin part (including documentation which is not really in par with the rest...), but it should not break anything developed now.
+- New system entity types may appear. 
+
+Anyway `PowerStencil` follows the semantic versioning pattern and if incompatible changes arise it may be reflected in the version.
+
+There are already some plugins in the pipe, especially around contenerization topics.
+
+:information_source: Of course, `PowerStencil` is new software and it is expected to evolve with the needs of its users...
+
+
+
+
+[:back:][Documentation root]
+<!-- End of Document -->
+
+<!-- Pages -->
+[Documentation root]: ../README.md "Back to documentation root"
+[entities]: entities.md "Entities in PowerStencil"
+[plugins]: plugins.md "Plugins in PowerStencil"
+[overrides]: builds.md#overriding-entities-and-build-scenarii "Overriding data locally"
+
+
+<!-- Code links -->
+
+
+<!-- Illustrations -->
+
+
+<!-- External links -->
+[CMDB]: https://en.wikipedia.org/wiki/Configuration_management_database "Configuration Management Database"

data/doc/templates.md

@@ -317,7 +317,7 @@ Flawless victory !!
 [builds]: builds.md "Builds in PowerStencil"
 [plugins]: plugins.md "Plugins in PowerStencil"
 [example use cases]: example_use_cases.md "Example uses cases using PowerStencil"
-[buildable]: entities.md#buildable--buildable_by "How to make an entity buildable ?"
+[buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?"
 
 <!-- Code links -->
 

data/etc/templates/project/.ps_project/personal-config.yaml

@@ -2,7 +2,7 @@
 # THIS FILE *IS NOT* MEANT TO BE VERSIONED (and is not by default)
 # You can use it for any configuration you want to keep local
 
-# debug
-:debug: false
+# :debug: true
 # :log-level: 2
-# :debug-on-stderr: true
+# :debug-on-stderr: true
+# :verbose: true

data/lib/power_stencil/project/config.rb

@@ -5,9 +5,9 @@ module PowerStencil
 
       include PowerStencil::Project::Paths
 
-      PROJECT_CONFIG_PRIORITY = 2000
-      USER_CONFIG_PRIORITY = 2010
-      PLUGIN_CONFIG_PRIORITY_MIN = 1000
+      PROJECT_CONFIG_PRIORITY = 990
+      USER_CONFIG_PRIORITY = 995
+      PLUGIN_CONFIG_PRIORITY_MIN = 100
 
       attr_reader :plugin_priority_count
 
@@ -16,6 +16,8 @@ module PowerStencil
         # Optional config files should have less priority than the command line layer
         add_optional_config_layer project_versioned_config_file, 'versioned project config file', PROJECT_CONFIG_PRIORITY
         add_optional_config_layer project_personal_config_file, 'personal project config file', USER_CONFIG_PRIORITY
+        Climatic.send :setup_logger
+        logger.debug 'Project config files loaded'
       end
 
 

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.3.5'.freeze
+  VERSION = '0.3.6'.freeze
 end

data/power_stencil.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
 
-  spec.add_dependency 'climatic', '~> 0.2', '>= 0.2.26'
+  spec.add_dependency 'climatic', '~> 0.2', '>= 0.2.28'
   spec.add_dependency 'dir_glob_ignore', '~> 0.3'
   spec.add_dependency 'universe_compiler', '~> 0.2', '>= 0.2.11'
   spec.add_dependency 'pry'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Laurent B.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-31 00:00:00.000000000 Z
+date: 2019-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -61,7 +61,7 @@ dependencies:
         version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.26
+        version: 0.2.28
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -71,7 +71,7 @@ dependencies:
         version: '0.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.26
+        version: 0.2.28
 - !ruby/object:Gem::Dependency
   name: dir_glob_ignore
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +143,7 @@ files:
 - doc/builds.md
 - doc/entities.md
 - doc/example_use_cases.md
+- doc/faq.md
 - doc/images/power-stencil-entity-build.svg
 - doc/images/power-stencil-entity-creation.svg
 - doc/images/power-stencil-simple-flow.svg
@@ -263,7 +264,7 @@ homepage: https://gitlab.com/tools4devops/power_stencil
 licenses:
 - MIT
 metadata: {}
-post_install_message: "\nThank you for installing PowerStencil 0.3.5 !\nFrom the command
+post_install_message: "\nThank you for installing PowerStencil 0.3.6 !\nFrom the command
   line you can run `power_stencil --help`\nIf your shell is not completing the command:\n
   \ If you use rbenv: `rbenv rehash`\n  If you use zsh  : `rehash`\n\nFull documentation
   here   : https://gitlab.com/tools4devops/power_stencil/blob/master/README.md\nFeel