power_stencil 0.4.7 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0422be311b723e5ba9d9f58e0884b73964359b96
-  data.tar.gz: 594d2a82611aef291f2dfcf9237282d1dcd4a0d0
+  metadata.gz: e5c65ac5df9e06a48f189b8b5abca257f80e8109
+  data.tar.gz: 24d671da7a9b7d63b06047b4319b08577d51c18b
 SHA512:
-  metadata.gz: cba7ef3b6731db7b4e5957536c5a8bfe182c6c533f8750d6a65baf4ba408aed245d32c62421ac652cbe7266a5c21cf6739a1ea3bb2d2f44fd7e3067e9e314c4f
-  data.tar.gz: 100ec840751ddfdba4e47bcb99769c666d7256f9882667f0da94c12987c1d6245947992c44772fc1511d98d402d3d8b9268b249eda5c7abcad08730d3f98260e
+  metadata.gz: 798153c2ea0a7dafd7c69fa011bbe9214e5cf34ec609a3449230ec094e9ec65839004c8f6bbd068182ff757135993601ba4417fc95f501147125d6365b3b1d2e
+  data.tar.gz: aabc03f3d18ab11f50f6c2790a94e817b626bf10d8762f35df2e42fa3b7db1dce7aaba8bcdbbe9b1ce4d47b3b631b388f610faa879bba31eb69dd5b787366fed

data/.gitlab-ci.yml

@@ -0,0 +1,9 @@
+image: "ruby:2.3"
+
+before_script:
+  - gem install bundler --no-document
+  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
+
+rspec:
+  script:
+    - bundle exec rspec

data/README.md

@@ -1,12 +1,17 @@
 PowerStencil
 ============
 
+[![ ](https://gitlab.com/tools4devops/power_stencil/badges/master/pipeline.svg)](https://gitlab.com/tools4devops/power_stencil/commits/master)
+
 `Power Stencil` is the Swiss-army knife templating workflow for developers and ops.
 
+See [official website][PowerStencil site].
+
+
 <!-- TOC -->
 
 - [Overview](#overview)
-- [Pfff, yet another templating engine...](#pfff-yet-another-templating-engine)
+- [Pfff, yet another templating engine...?](#pfff-yet-another-templating-engine)
 - [Installation](#installation)
 - [Usage](#usage)
     - [Help](#help)
@@ -28,7 +33,7 @@ PowerStencil
 
 `PowerStencil` proposes a radical approach on how to manage your shared configuration.
 
-**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.
+**Configuration** is one of the most complex things to maintain, and anyone who participated in a large scale piece of software, be it for code, tools configuration or even 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.
 
 From a very high level point of view, the workfow `PowerStencil` proposes looks like:
 
@@ -36,7 +41,7 @@ From a very high level point of view, the workfow `PowerStencil` proposes looks
 
 `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 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... ?
+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.][DB in 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... ?
 
 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.
 
@@ -48,22 +53,25 @@ The `PowerStencil` gem provides the `power_stencil` executable which is a plugga
 - Visualize your **data relations with graphviz**. Customize generated graphs easily.
 - Easily **manage templates** to generate whatever your project/organization requires.
 - Define builds that you can easily **embed in your CI/CD process** or use them standalone.
-- Ensure **re-usability** with a versatile extension mechanism including plugins.
+- Propose mechanism to temporarily override some data to test changes impact without polluting the official repository data.
+- Ensure **re-usability** with a versatile extension mechanism, including plugins.
 
-# Pfff, yet another templating engine...
+# Pfff, yet another templating engine...?
 
 **Actually `PowerStencil` is _not_ a templating engine**. It uses already existing and proven templating engines.
 
-Currently it uses [ERB], which is a pretty standard and very well known engine in the [Ruby] world and especially for people who already used the [Rails] framework. Virtually any templating engine existing in the Ruby ecosystem could be integrated in the `PowerStencil` framework next to [ERB]. This will probably be the case in a future release, at least to integrate the [Haml] templating engine in order to ease the generation of XML-like files, still you obviously already can do it with [ERB].
+Currently it uses [ERB], which is a pretty standard and very well known engine in the [Ruby] world and especially for people who already used the [Rails] framework. Virtually any templating engine existing in the Ruby ecosystem could be integrated in the `PowerStencil` framework next to [ERB] (as `PowerStencil` already comes with a mechanism to select a templating engine regarding some criteria like file extension, path etc...). 
+
+This will probably be the case in a future release, at least to integrate the [Haml] templating engine in order to ease the generation of XML-like files, still you obviously already can do it with [ERB].
 
-No, the real value of `PowerStencil` is in the development flow it proposes around this templating mechanism, for both development and/or operations teams, and most specifically in **the way you organize and trace the data which is the real asset**, and in the way you can easily extend it to fit the particular needs of a project or organization.
+So `PowerStencil` is definitely not a templating it is actually much more than that.
 
 
 # Installation
 
 You need a working install of the [Ruby] language (>= 2.3).
 
-You can install the `PowerStencil` gem by issuing the usual:
+Then you can install the `PowerStencil` gem by issuing the usual:
 
     $ gem install power_stencil
 
@@ -75,7 +83,7 @@ If you want to create graphviz graphs, you probably may want to install it for y
 
 ## Help
 
-The `power_stencil` CLI provides a contextual help. You can start by:
+The `power_stencil` CLI provides a contextual help. You can begin with:
 
     $ power_stencil --help
 
@@ -120,13 +128,13 @@ The program uses the standard paradigm of sub-commands (à-la-git), and each can
 
 ## Creating a `PowerStencil` project
 
-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):
+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 enough rights on the filesystem):
 
     $ power_stencil init /where/you/want/your/project
 
 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: The rest of this documentation will assume you are at the root of this created project.**
 
 **:information_source: Of course, once you've been creating a new project, you should version it with Git:**
 
@@ -162,12 +170,12 @@ Not all the files in this directory should be versioned, and this the reason why
 
 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. 
+- Keep the official project config in the `.ps_project/versioned-config.yaml` which, as its name suggest, will be git versioned.
+- But any developer who wants to temporarily override some configuration should do it in the `.ps_project/personal-config.yaml`, which is not to be versioned. The content defined in the latter will override the content of the versioned 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.**
 
-There is the same mechanism between `.ps_project/entities` (where the project data is stored and which is versioned) and `.ps_project/user_entities` (where local data is stored and not versioned), but as opposed to the two aforementioned config files, you should not edit anything directly there but instead use the CLI or the shell. More information on how to manage entities [here][entities].
+There is the same mechanism between `.ps_project/entities` (where the project data is stored and which is versioned) and `.ps_project/user_entities` (where local data is stored and not versioned), but as opposed to the two aforementioned config files, you should not edit anything directly there, but instead use the CLI or the shell. More information on how to manage entities [here][entities].
 
 The `plugins` directory can optionally contain project specific plugins. Plugins are a great way to extend `PowerStencil` for the needs of a project or organization.
 
@@ -223,6 +231,7 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [example use cases]: doc/example_use_cases.md "Example uses cases using PowerStencil"
 [F.A.Q.]: doc/faq.md "PowerStencil F.A.Q."
 [status in the F.A.Q.]: doc/faq.md#what-is-the-status-of-powerstencil- "PowerStencil project status"
+[DB in F.A.Q.]: doc/faq.md#why-is-a-real-database-a-bad-idea-as-configuration-store-for-cicd- "Databases in build processes"
 [code of conduct]: CODE_OF_CONDUCT.md
 
 <!-- Code links -->
@@ -236,4 +245,5 @@ Everyone interacting in the PowerStencil project’s codebases, issue trackers,
 [ERB]: https://ruby-doc.org/stdlib-2.6.3/libdoc/erb/rdoc/ERB.html "Quick ERB description"
 [Haml]: http://haml.info/ "The templating engine for XML-like documents"
 [Ruby]: https://www.ruby-lang.org "The powerful Ruby language"
-[Rails]: https://rubyonrails.org/ "The Ruby on Rails framework"
+[Rails]: https://rubyonrails.org/ "The Ruby on Rails framework"
+[PowerStencil site]: https://powerstencil.brizone.org "Official PowerStencil website"

data/doc/builds.md

@@ -16,6 +16,7 @@ Builds
 
 # Overview of the build process
 
+**:warning: You should have already read the documentation about [templates], before reading this.**
 
 You build a [buildable] entity by issuing `power_stencil build <entity_type>/<entity_name>`. If you try to build an entity which is not buildable, the process fail with an error message.
 
@@ -115,7 +116,7 @@ You may have noticed from the output of `power_stencil info` that there is a typ
 
 This is a very specific type of entity linked to the compilation process.
 
-The goal of this specific entity is to provide a mechanism to override some of the properties of other entities in the scope of a _build scenario_. This is really a feature turned towards testing possibilities, by it for developers or ops, and as such generally `entity_override` are often created as [local entities] (although they really could be created as standard versioned entities).
+The goal of this specific entity is to provide a mechanism to override some of the properties of other entities in the scope of a _build scenario_. This is really a feature turned towards testing possibilities, be it for developers or ops, and as such generally `entity_override` are often created as [local entities] (although they really could be created as standard versioned entities).
 
 Let's create our first override:
 

data/doc/entities.md

@@ -10,7 +10,7 @@ Entities
     - [Loose schema entities](#loose-schema-entities)
 - [Manipulating entities](#manipulating-entities)
     - [Checking entities](#checking-entities)
-    - [Querying entities](#querying-entities)
+    - [Querying and graphing entities](#querying-and-graphing-entities)
     - [Creating entities](#creating-entities)
         - [Versioned entities](#versioned-entities)
         - [Local (unversioned) entities](#local-unversioned-entities)
@@ -226,7 +226,7 @@ RAW ENTITIES
   - Buildable   : false
 ```
 
-## Querying entities
+## Querying and graphing entities
 
 The command to query entities from the repository is `power_stencil get`, and it works basically like the `power_stencil check` command.
 
@@ -874,7 +874,7 @@ So you see that if we try to set parent with something wrong, the accessor seems
 
 :information_source: The `name` property of the `has_one` directive is optional. If not present the field will be named from the entity_type referenced instead...
 
-**:information_source: See more advanced features, like the very powerful reverse methods in the [`universe_compiler` advanced relations documentation].**
+**:information_source: See more advanced features, like the very powerful reverse methods in the [`universe_compiler` advanced relations documentation].** [universe_compiler] is the Gem that manages entities under the hood, but it is much lower level than `PowerStencil`, so unless you are really interested in what happens under the hood, you should not really care about it. Yet you should definitely check what the `with_reverse_method` and `unique` options do to the `has_one` directive.
 
 #### has_many
 
@@ -924,7 +924,7 @@ Which translates at persistence level as:
 ```
 Nice !
 
-**:information_source: See more advanced features, like the very powerful reverse methods in the [`universe_compiler` advanced relations documentation].**
+**:information_source: See more advanced features, like the very powerful reverse methods in the [`universe_compiler` advanced relations documentation].** [universe_compiler] is the Gem that manages entities under the hood, but it is much lower level than `PowerStencil`, so unless you are really interested in what happens under the hood, you should not really care about it. Yet you should definitely check what the `with_reverse_method` and `unique` options do to the `has_many` directive.
 
 
 ### buildable and buildable_by

data/doc/faq.md

@@ -76,7 +76,8 @@ 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.
-- The documentation is evolving
+- The functional documentation is evolving.
+- There is almost no technical/architectural documentation yet. Read the code...
 
 Anyway `PowerStencil` follows the semantic versioning pattern and if incompatible changes arise it may be reflected in the version.
 

data/doc/plugins.md

@@ -44,7 +44,7 @@ The normal process would be to begin with a plugin within the project and once y
 - Plugins local to the project are automatically taken in account.
 - To use plugins provided as Gems you have to set the `:plugins:` array property in the `.ps_project/versioned-config.yaml`
 
-:warning: Plugins provided as standalone Gems are not thoroughly tested, for the time being you may use plugins local to the project.
+:warning: Plugins provided as standalone Gems are not thoroughly tested, for the time being, you may use plugins local to the project.
 
 
 # Creating plugin local to the project
@@ -145,9 +145,9 @@ MYPLUGIN PLUGIN WAZ HERE
 Wow it worked ! Useless, but worked !
 
 
-The documentation for plugins is not yet done, so you are encouraged to read the code, the capabilities (in the output of `power_stencil info`) give you an idea of what plugins can do.
+The documentation for plugins is not yet done, so you are encouraged to read the code, the `capabilities` (in the output of `power_stencil info`) give you an idea of what plugins can do. Some official plugins are under development, and the documentation will be improved along their development...
 
-:warning: As opposed to the rest of `PowerStencil`, the functionnality is nevertheless not completely frozen.
+**:warning: As opposed to the rest of `PowerStencil`, the functionnality is nevertheless not completely frozen. This will be the case once `PowerStencil` turns 1.0.0.**
 
 
 [:back:][Documentation root]

data/doc/templates.md

@@ -19,6 +19,8 @@ Templates
 
 # Templates overview
 
+**:warning: You should have already read the documentation about [entities], before reading this.**
+
 Template is a key feature of `PowerStencil` (hence the name). In templates you define how you will use the [entities] you carefully crafted in order to produce something during a [build][builds] process.
 
 The default templating engine being [ERB], your templates should be written using the [ERB] syntax, like most templates are written in the [Ruby On Rails] framework. This is basically some [Ruby] inside some ERB tags.

data/lib/power_stencil/plugins/gem.rb

@@ -5,7 +5,7 @@ module PowerStencil
 
     module Gem
 
-      NO_DOC = %w(--no-ri --no-rdoc).freeze
+      NO_DOC = %w(--no-document).freeze
 
       def gem_locally_installed?(plugin_name, plugin_requirements)
         get_spec(plugin_name, plugin_requirements).nil? ? false : true

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.4.7'.freeze
+  VERSION = '0.4.8'.freeze
 end

data/power_stencil.gemspec

@@ -6,12 +6,12 @@ require 'power_stencil/version'
 Gem::Specification.new do |spec|
   spec.name          = 'power_stencil'
   spec.version       = PowerStencil::VERSION
-  spec.authors       = ['Laurent B.']
-  spec.email         = ['lbnetid+rb@gmail.com']
+  spec.authors       = ['Laurent Briais']
+  spec.email         = ['powerstencil-contact@brizone.org']
 
   spec.summary       = %q{PowerStencil is the Swiss-army knife templating workflow for developers and ops.}
   spec.description   = %q{PowerStencil is the Swiss-army knife templating workflow for developers and ops.}
-  spec.homepage      = 'https://gitlab.com/tools4devops/power_stencil'
+  spec.homepage      = 'https://powerstencil.brizone.org'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.4.8
 platform: ruby
 authors:
-- Laurent B.
+- Laurent Briais
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-18 00:00:00.000000000 Z
+date: 2019-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -111,13 +111,14 @@ dependencies:
 description: PowerStencil is the Swiss-army knife templating workflow for developers
   and ops.
 email:
-- lbnetid+rb@gmail.com
+- powerstencil-contact@brizone.org
 executables:
 - power_stencil
 extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".gitlab-ci.yml"
 - ".rspec"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
@@ -249,15 +250,15 @@ files:
 - lib/power_stencil/utils/semantic_version.rb
 - lib/power_stencil/version.rb
 - power_stencil.gemspec
-homepage: https://gitlab.com/tools4devops/power_stencil
+homepage: https://powerstencil.brizone.org
 licenses:
 - MIT
 metadata: {}
-post_install_message: "\nThank you for installing PowerStencil 0.4.7 !\nFrom the command
+post_install_message: "\nThank you for installing PowerStencil 0.4.8 !\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
-  free to report issues: https://gitlab.com/tools4devops/power_stencil/issues\n  "
+  here   : https://powerstencil.brizone.org/blob/master/README.md\nFeel free to report
+  issues: https://powerstencil.brizone.org/issues\n  "
 rdoc_options: []
 require_paths:
 - lib