power_stencil 0.8.3 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8df74429279b0f913ba3fda4b6c296dc6053945a
-  data.tar.gz: 78fb02e5902690f445106a79ec6a2d36d4f2e3df
+  metadata.gz: 381fd5ec322002d77a04968f74f74fa9e3a180d9
+  data.tar.gz: fc328939af39ca43740d39170af6fcbd3d9e2979
 SHA512:
-  metadata.gz: 1db0ca206eff645bece9e2d68abae5a95848ae2feaa71786aae605337ee4b848c447d123a1d0cd9905f6daf567216712d780b5ee6c9f302c458f22fab3f04aeb
-  data.tar.gz: cb16ab5ad26dec5f5917e2f5e931f54dab0fae361959aff735d51b6f2a153378884a15e3c495ec5eafacbcf7c4339fff6da38099177e1a2cd36c3c49aa68f87c
+  metadata.gz: f6fd159bec0d10364cce84d2e6184d8f7708c8387f2e6f09754a95f34d5855fde0141a39e47d079bb39ae37b381b4cf864e87181f3dc5b71cec1472a5fd4145d
+  data.tar.gz: cb84a9ddc19a5a8106d9a14f1cdc9058588be4dfef89c90f3cbb64d2e30ec94012bbf017088197d2596b79da07d123a38b2dba8a98d07112e9693ad9b2335ece

data/README.md

@@ -23,6 +23,7 @@ See [official website][PowerStencil site].
         - [Templates](#templates)
         - [Builds](#builds)
         - [Plugins](#plugins)
+        - [Git integration](#git-integration)
 - [Project status](#project-status)
 - [Contributing](#contributing)
     - [License](#license)
@@ -153,7 +154,7 @@ Once the project created, if you are anywhere within the project tree, you don't
 
 **:information_source: The rest of this documentation will assume you are at the root of this created project.**
 
-**:information_source: If you have `git` installed on your system, **the repository of the newly created project has been automatically turned into a git repository. And any action done through the `power_stencil` command-line will be automatically tracked by `git`**. Only things you will do outside of the `power_stencil` command-line (adding or modifying templates, creating or modifying entity types... any manual action) will require a user action to make `git` take it in account. You can completely de-activate this behaviour if you want to fully manage things by yourself by adding `:no-git: true` in the `.ps_project/versioned-config.yaml`, yet there is no good reason for that... Unless you know what you are doing, you should keep the default settings.
+**:information_source: If you have `git` installed on your system, **the repository of the newly created project has been automatically turned into a git repository. And any action done through the `power_stencil` command-line will be automatically tracked by `git`**. Only things you will do outside of the `power_stencil` command-line (adding or modifying templates, creating or modifying entity types... any manual action) will require a user action to make `git` take it in account. You can completely de-activate this behaviour if you want to fully manage things by yourself by adding `:no-git: true` in the `.ps_project/versioned-config.yaml`, yet there is no good reason for that... Unless you know what you are doing, you should keep the default settings. See [Git integration] for further information.
 
 ## `PowerStencil` project structure
 
@@ -211,10 +212,13 @@ The mechanism that **combines entities and templates** is called a **[build][bui
 `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` and ease cross-projects share and re-usability**, 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...
 
-<br>
+### Git integration
+
+Git is closely integrated at the heart of `PowerStencil`. See how works the [Git integration].
+
 <br>
 
-And course, you may want to **read the [F.A.Q.]**
+And of course, you may want to **read the [F.A.Q.]**
 
 # Project status
 
@@ -240,6 +244,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"
+[Git integration]: doc/git_integration.md "See of git is integrated with 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"

data/doc/git_integration.md

@@ -0,0 +1,364 @@
+Git integration
+===============
+<!-- TOC -->
+
+- [Overview](#overview)
+- [`PowerStencil` "_write_" actions](#powerstencil-_write_-actions)
+- [Activating / De-activating integration](#activating--de-activating-integration)
+    - [Generic config flag](#generic-config-flag)
+- [How things are tracked](#how-things-are-tracked)
+    - [Project creation](#project-creation)
+    - [Entity creation](#entity-creation)
+    - [Modifying an entity](#modifying-an-entity)
+    - [Deleting an entity](#deleting-an-entity)
+    - [`PowerStencil` shell session](#powerstencil-shell-session)
+    - [Plugin creation](#plugin-creation)
+- [Manual actions](#manual-actions)
+
+<!-- /TOC -->
+[:back:][Documentation root]
+
+
+# Overview
+
+The git integration within `PowerStencil` provides tons of useful default behaviors. Let's browse what it brings out of the box.
+
+:hand: You should have already read the whole [Getting Started] part before reading this.
+
+
+# `PowerStencil` "_write_" actions
+
+When interacting with `PowerStencil`, only some of the commands actually trigger write actions on your disk.
+
+Here is a summary:
+
+<a name="subcommands-impact"></a>
+
+| `PowerStencil` sub-command | Status |
+|----------------------------|:------:|
+|init        | creates a project
+|info        | read-only
+|plugin      | creates a plugin
+|get         | read-only
+|shell       | do anything  
+|adm         | read-only
+|check       | read-only  
+|create      | creates entities
+|edit        | modifies entities
+|delete      | deletes entities
+|describe    | read-only
+|build       | read-only  
+
+On top this we could add some other actions, you can obviously perform manually within the repository, like:
+
+* Create/update/delete entity types
+* Create/update/delete entity type templates-templates
+* Code within local plugins
+* Create/update/delete templates for buildable entities
+* Modify `.ps_project/versioned-config.yaml` config file (the file `.ps_project/personal-config.yaml` is unversioned)
+* ... and of course anything else, not `PowerStencil` related, you would like add to your project.
+
+**:+1: The git integration will not interfere with any of your manually done actions and will keep anything you are doing manually out of scope of automatically generated git commits.**
+
+# Activating / De-activating integration
+
+## Generic config flag
+
+You can specify in the `.ps_project/versioned-config.yaml` config file that you don't want to activate the git integration by adding:
+
+```yaml
+:no-git: true
+```
+
+And then nothing will be automatically tracked by git. It could be also activated in your personal config file (`.ps_project/personal-config.yaml`) if you you temporarily want to manage commits manually for whatever strange reason.
+
+Still if you do that, when you initially created the project a git repository has been created. But if you want to completely stay out of git and for example use another versioning tool (does it still exist ??), you can create your project without git integration by doing:
+
+    $ power_stencil init my_project --no-git
+
+In this case the setting inside your config file is not even necessary.
+Or course you could _a posteriori_ delete the `.git` directory, but why would you want to do that...
+
+:warning: Be careful that the `.gitignore` file is there to normally ensure that only things that really need to be committed are actually. So it means that if you use a different versionning tool, you have to somehow translate this `.gitignore` file in the paradigm of the tool you actually use !
+
+
+:information_source: One legitimate reason to temporarily avoid automatic git commit may be for plugin creation, but we'll see that in the next paragraph.
+
+# How things are tracked
+
+Each command not stated as "read-only" in the [table above](#subcommands-impact), actually generate a git commit. Let's see that in detail.
+
+## Project creation
+
+When a project is created with:
+
+    $ power_stencil init test
+
+A git repository is automatically created, initial project files are added to git staging and a first commit is done. So from the project directory we can see:
+
+```
+$ git log --full-history --summary 
+commit a5cc500277d8a58d78111e1accdeff7f72fc3027
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 3 18:31:20 2019 +0100
+
+    Initial commit for project "test".
+
+ create mode 100644 .gitignore
+ create mode 100644 .ps_project/entities/README.md
+ create mode 100644 .ps_project/entity_definitions/README.md
+ create mode 100644 .ps_project/plugins/README.md
+ create mode 100644 .ps_project/templates-templates/README.md
+ create mode 100644 .ps_project/versioned-config.yaml
+```
+So you see by default all the files which have been committed.
+
+## Entity creation
+
+To make the things a bit more fun, let's do it with an entity that generates templates like a `simple_exec`:
+
+    $ power_stencil create simple_exec/foo
+
+```
+$ git log -1 --summary
+commit 00a09a274377c0797061b342b61ebab028189163
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 3 18:55:12 2019 +0100
+
+    Created 'simple_exec/foo' (and potential dependencies).
+
+ create mode 100644 .ps_project/entities/process_descriptor/simple_exec_foo.process.yaml
+ create mode 100644 .ps_project/entities/simple_exec/foo.yaml
+ create mode 100755 templates/simple_exec/foo/main.sh
+```
+
+:+1: Yeah, all files generated are committed at once, including the `process_descriptor` it automatically creates as well as the templates generated. Pretty cool...
+
+In the end it gives a pretty understandable history:
+
+```
+$ git log --oneline
+00a09a2 Created 'simple_exec/foo' (and potential dependencies).
+a5cc500 Initial commit for project "test".
+```
+And of course the working directory remains clean:
+```
+$ git status
+On branch master
+nothing to commit, working tree clean
+```
+
+## Modifying an entity
+
+Of course you probably guessed it now, if you edit the `simple_exec/foo` entity using, the:
+
+    $ power_stencil edit simple_exec/foo
+
+```
+$ git log -1 --summary
+commit 7de417f51f7ca37a4e81b7dee968affaa437f383
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 3 19:10:44 2019 +0100
+
+    Edited entity 'simple_exec/foo'.
+```
+And of course you can track the changes.
+
+```
+$ git diff 00a09a2
+diff --git a/.ps_project/entities/simple_exec/foo.yaml b/.ps_project/entities/simple_exec/foo.yaml
+index 710b97f..1d9cc26 100644
+--- a/.ps_project/entities/simple_exec/foo.yaml
++++ b/.ps_project/entities/simple_exec/foo.yaml
+@@ -1,3 +1,4 @@
+ --- !ruby/object:PowerStencil::SystemEntityDefinitions::SimpleExec
+ :name: foo
+ :post_process: !entity process_descriptor/simple_exec_foo.process
++:description: A useless entity
+```
+**:hand: But of course, if I modify the templates by editing manually the `templates/simple_exec/foo/main.sh` file, or by adding new files in the template directory of this entity, I will have to manage them manually like I would normally do with any file tracked by git.**
+
+## Deleting an entity
+
+When deleting an entity, `PowerStencil` offers to delete the entity only with:
+
+    $ power_stencil delete simple_exec/foo
+
+Or to delete it, including its associated templates with:
+
+    $ power_stencil delete simple_exec/foo --delete-files
+
+In both cases, the git integration will track things correctly. Let's say we choose the second option:
+
+
+```
+$ power_stencil delete simple_exec/foo --delete-files --auto
+Deleting entity 'simple_exec/foo'
+Deleted 'simple_exec/foo' and template files.
+
+$ git log -1 --summary
+commit 1193c1c961fc2eecc50dea93b5f76411797f415b
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 3 19:27:44 2019 +0100
+
+    Deleted entity 'simple_exec/foo' (and potential dependencies) including templates..
+
+ delete mode 100644 .ps_project/entities/process_descriptor/simple_exec_foo.process.yaml
+ delete mode 100644 .ps_project/entities/simple_exec/foo.yaml
+ delete mode 100755 templates/simple_exec/foo/main.sh
+```
+
+## `PowerStencil` shell session
+
+You can do a lot of things within a shell session, and sometimes even destructive actions you may not want to commit. This is why `PowerStencil` will ask you if you want to commit your changes and present you with the list of changes. Here under a sample session:
+
+```
+$ power_stencil shell 
+Please report a bug if this causes problems.
+-------------------------------------------------------------------------------
+ Welcome to the PowerStencil shell session
+ In this shell you have access to anything the templating engine has access to.
+ On top of this, you can view, edit, save and delete entities.
+
+ - Retrieve and manipulate entities using the `entities` hash.
+ - Persist your changes using the `save` method on each entity.
+ - Create new project or user entities using `new_<entity_type>` and
+   `user_new_<entity_type>` methods (see `available_entity_types` for a list of
+   possible types).
+ - And of course, it is a fully fledged Ruby Pry REPL, so you can do anything
+   you want...
+
+ Type `exit` to end your session.
+-------------------------------------------------------------------------------
+
+PowerStencil DSL> e = new_simple_exec name: :test2
+=> #<PowerStencil::SystemEntityDefinitions::SimpleExec:47357208924260 composite_key=[:simple_exec, "test2"], @universe='Project entities (1572805960.765458)'>
+PowerStencil DSL> e.save
+=> #<PowerStencil::SystemEntityDefinitions::SimpleExec:47357208924260 composite_key=[:simple_exec, "test2"], @universe='Project entities (1572805960.765458)'>
+PowerStencil DSL> exit
+Following files will be committed:
+ - '.ps_project/entities/process_descriptor/simple_exec_test2.process.yaml'
+ - '.ps_project/entities/simple_exec/test2.yaml'
+ - 'templates/simple_exec/test2/main.sh'
+Would you like to commit your changes ? ([Yes]/y/No/n): y
+
+$ git log -1 --summary
+commit 8c8554b297a05466147208ca657323300e952981
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 3 19:33:25 2019 +0100
+
+    Changes done in PowerStencil shell session.
+
+ create mode 100644 .ps_project/entities/process_descriptor/simple_exec_test2.process.yaml
+ create mode 100644 .ps_project/entities/simple_exec/test2.yaml
+ create mode 100755 templates/simple_exec/test2/main.sh
+```
+
+You see the commit is labelled `Changes done in PowerStencil shell session`.
+
+
+:information_source: If you have not introduced any change, the question will not even be asked when you exit the shell...
+
+## Plugin creation
+
+As expected if you create a plugin using the command:
+
+    $ power_stencil plugin --create bar
+
+It tracks this as well:
+
+```
+$ git log -1 --summary
+commit 591df0951a04476ebe29284fda8fd548c638dcea
+Author: Joe <joe@outerspace.org>
+Date:   Sun Nov 3 19:42:11 2019 +0100
+
+    Generated new local plugin 'bar'.
+
+ create mode 100644 .ps_project/plugins/bar/.gitignore
+ create mode 100644 .ps_project/plugins/bar/.rspec
+ create mode 100644 .ps_project/plugins/bar/.travis.yml
+ create mode 100644 .ps_project/plugins/bar/CODE_OF_CONDUCT.md
+ create mode 100644 .ps_project/plugins/bar/Gemfile
+ create mode 100644 .ps_project/plugins/bar/LICENSE.txt
+ create mode 100644 .ps_project/plugins/bar/README.md
+ create mode 100644 .ps_project/plugins/bar/Rakefile
+ create mode 100644 .ps_project/plugins/bar/bin/console
+ create mode 100644 .ps_project/plugins/bar/bin/setup
+ create mode 100644 .ps_project/plugins/bar/etc/command_line.yaml
+ create mode 100644 .ps_project/plugins/bar/etc/plugin_capabilities.yaml
+ create mode 100644 .ps_project/plugins/bar/etc/plugin_config.yaml
+ create mode 100644 .ps_project/plugins/bar/etc/templates/.git_keep
+ create mode 100644 .ps_project/plugins/bar/etc/templates/bar_entity/.copy_ignore
+ create mode 100644 .ps_project/plugins/bar/etc/templates/bar_entity/.subst_ignore
+ create mode 100644 .ps_project/plugins/bar/etc/templates/bar_entity/message.txt
+ create mode 100644 .ps_project/plugins/bar/lib/bar.rb
+ create mode 100644 .ps_project/plugins/bar/lib/bar/bar_processor.rb
+ create mode 100644 .ps_project/plugins/bar/lib/bar/dsl/bar_dsl.rb
+ create mode 100644 .ps_project/plugins/bar/lib/bar/entity_definitions/bar_entity.rb
+ create mode 100644 .ps_project/plugins/bar/lib/bar/plugin_helper.rb
+ create mode 100644 .ps_project/plugins/bar/lib/bar/version.rb
+ create mode 100644 .ps_project/plugins/bar/psplugin_bar.gemspec
+ create mode 100644 .ps_project/plugins/bar/spec/bar_spec.rb
+ create mode 100644 .ps_project/plugins/bar/spec/spec_helper.rb
+```
+
+Cool ! Nevertheless, plugins may be one of the things you may want to track a bit differently. For example as git sub-modules, to keep a separated git history, and ease future re-useability of the plugin you are developing.
+So it's up to you and `PowerStencil` provides an easy way to keep your plugin out of your project repo. Same as for `power_stencil init`, `power_stencil plugin --create` supports the `--no-git` option...
+
+# Manual actions
+
+Ok, so far we have a pretty nice git history:
+
+```
+$ git log --oneline
+591df09 Generated new local plugin 'bar'.
+8c8554b Changes done in PowerStencil shell session.
+1193c1c Deleted entity 'simple_exec/foo' (and potential dependencies) including templates..
+7de417f Edited entity 'simple_exec/foo'.
+00a09a2 Created 'simple_exec/foo' (and potential dependencies).
+a5cc500 Initial commit for project "test".
+```
+
+And our working directory is still clean.
+
+```
+$ git status
+On branch master
+nothing to commit, working tree clean
+```
+
+But what happens if we modify things manually ? How does it interfere with everything we saw before.
+
+:wink: Actually, before any action, `PowerStencil` gets a snapshot of the working directory in terms of git modifications (added, removed, modified, moved files...) and **will not include any of this pre-existing changes in its own commits**.
+
+It's actually, a good separation of responsibilities. If you modified something by yourself, you are responsible to commit the changes (or not)...
+
+In the end, it means you have to completely manage by yourself any changes you would apply to:
+
+* the main config file (`.ps_project/versioned-config.yaml`)
+* entity types creation, modification, deletion (under `.ps_project/entity_definitions/`).
+* template-templates creation, modification, deletion for your own entity types (under `.ps_project/templates-templates/`).
+* entity templates added and any modification (under `templates`).
+* code changes in your local plugins (`.ps_project/plugins/`)
+
+
+[: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"
+[example use cases]: example_use_cases.md "Example uses cases using PowerStencil"
+[Getting Started]: ../README.md#getting-started "Getting Started with PowerStencil"
+
+<!-- Code links -->
+
+
+<!-- Illustrations -->
+
+
+<!-- External links -->
+

data/lib/power_stencil/project/git.rb

@@ -61,6 +61,7 @@ module PowerStencil
       attr_reader :git
 
       def setup_git_tracking
+        require 'git'
         @git = nil
         if config[:'no-git']
           logger.debug "Won't track any changes with git as per config request!"

data/lib/power_stencil/version.rb

@@ -1,3 +1,3 @@
 module PowerStencil
-  VERSION = '0.8.3'.freeze
+  VERSION = '0.8.4'.freeze
 end

data/lib/power_stencil.rb

@@ -1,7 +1,6 @@
 require 'power_stencil/version'
 
 require 'universe_compiler'
-require 'git'
 require 'dir_glob_ignore'
 
 $DO_NOT_AUTOSTART_CLIMATIC=true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: power_stencil
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.8.4
 platform: ruby
 authors:
 - Laurent Briais
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-02 00:00:00.000000000 Z
+date: 2019-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -147,6 +147,7 @@ files:
 - doc/entities.md
 - doc/example_use_cases.md
 - doc/faq.md
+- doc/git_integration.md
 - doc/images/power-stencil-entity-build.svg
 - doc/images/power-stencil-entity-creation.svg
 - doc/images/power-stencil-simple-flow.svg
@@ -298,7 +299,7 @@ metadata:
   documentation_uri: https://gitlab.com/tools4devops/power_stencil/blob/master/README.md
   source_code_uri: https://gitlab.com/tools4devops/power_stencil
   homepage_uri: https://powerstencil.brizone.org/
-post_install_message: "\nThank you for installing PowerStencil 0.8.3 !\nFrom the command
+post_install_message: "\nThank you for installing PowerStencil 0.8.4 !\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\nOfficial Website
   \         : https://powerstencil.brizone.org/\nFull documentation here   : https://gitlab.com/tools4devops/power_stencil/blob/master/README.md\nFeel