mdt-core 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 670a148d5a8ff620a0fce35e9f82f5becca15c908fd3937c8c8f9b55581d1dd6
-  data.tar.gz: 4584b1ef1bfd9ac6dbd23fa8362a76e4fc02904f472fece82e99899520b267b9
+  metadata.gz: 5f5302dd44719fbcd4484a84a8438421edd7b85532663df5ce94ac00ba4a3c93
+  data.tar.gz: 60de727f66d701fb2db324f943a07f80eb4e5d069277804c8565fbb4ff7c0834
 SHA512:
-  metadata.gz: 8812a886a54722d0e85be85aa6336ae066e98b1634e3e29a75a4e543f2568ef409cdf27510b3bc22051cdf88f601b7dcd2bdb9a8aa861cf4e35aaa0b26590a6b
-  data.tar.gz: 46a38d1a5b44523c86ae8a24616e9154234d422ef6ca39bd92bcbf964cc50439d06c5cab0956141def6b61de75fca1008a4eea323c3a015b08df41ec76160e63
+  metadata.gz: aa6c396dcb98ab54208fdbec4791aa0c82a633b0ea1d8ce954d1438196f7bf199c5a94425cebc72b115d5a47dbc8a80bbad4451b3e1eb5e8063bf244eca300eb
+  data.tar.gz: c65921bdc2bf5dd9ef37b244aaaa505ecf3e72ce3c0b6600f4154210458541253843223cb7fc815b81f964acd385e121aceec3edbdea1b2f06d818f56b354811

data/MODULE_GUIDELINES.md

@@ -0,0 +1,65 @@
+# Module creation guidelines
+
+There are a few things to take into account when creating a MDT module. This document is an attempt to summarize them.
+
+## Gem naming convention
+
+Because of the way MDT handles autoloading gems, you should always use `mdt-<something>` as a name of the gem. Otherwise the autoloading process will not include them and that may cause problems with the users of your module.
+
+## Gem structure
+
+An MDT module gem should have the following structure:
+
+```
+-- Gemfile
+-- Gemfile.lock
+-- mdt-<something>.gemspec
+-- .gitignore
+-- LICENSE
+-- README.md
+-- lib
+  |
+  -- mdt-<something>.rb
+  -- mdt
+    |
+    -- version.rb
+    -- fetchers.rb
+    -- directory_choosers.rb
+    -- commands.rb
+    -- command_modifiers.rb
+    -- fetchers
+      |
+      <fetchers_key>.rb
+      ...
+    -- directory_choosers
+      |
+      <directory_choosers_key>.rb
+      ...
+    -- commands
+      |
+      <commands_key>.rb
+      ...
+    -- command_modifiers
+      |
+      <command_modifiers_key>.rb
+      ...
+-- spec
+```
+
+The most important thing to remember is that the top file in lib should be named exactly as a gem because of the MDT autoloading process. The rest is just an example, if your module does not define a subclass for a particular object type then it is not required.
+
+## Module separation convention
+
+A module can include commands for a programming language and its standard tooling or custom tools. It can also define a flow using directory choosers and/or fetchers. A decision whether or not to separate the objects to a separate module or to keep them together in one should take these points into account:
+
+* When making a module for a programming language it should refer only to the standard tools included with the language. Any additional tools should be separated to their own modules.
+
+* When making a module that includes a way to fetch a code with a particular tool or to choose a deploy directory with the use of a particular tool or flow, it should also include commands and command modifiers related to the tool or flow. When making a module that uses a tool to define commands or command modifiers, it should also include fetchers or directory choosers if it can be used to define a deploy flow. A module for a particular tool or flow should be single and as complete as possible.
+
+## Module distribution
+
+MDT modules that meet these guidelines should be distributed as gems, preferrably through the official RubyGems service.
+
+## Testing and documentation
+
+Modules should be tested and documented as good as possible.

data/README.md

@@ -0,0 +1,44 @@
+# MDT - Modular Deployment Tool (Core)
+
+MDT is a deployment automation tool that is designed to be simple and easily extended by additional modules. It is written in Ruby and takes advantage of Ruby tools, but it can be used to deploy almost anything if there is a module for it.
+
+## Requirements
+
+* Ruby (tested with 2.5.0, earlier versions down to 2.0 may also work)
+* RubyGems
+
+## Installation
+
+`gem install mdt-core`
+
+Be sure to also install any modules that you need.
+
+## Usage
+
+The gem installs an executable called `mdt` that is used in a way described below:
+
+`mdt [options] <config_key>`
+
+By default it searches for the deployment configuration in `config/mdt-deploy.yml`. Options can be any of: `-c CONFIG_FILE_PATH`, `--config CONFIG_FILE_PATH`, `-h`, `--help`. `config_key` is required.
+
+## Deployment configuration file
+
+See `config/mdt-deploy.yml.example` for example deployment configuration file with comments.
+
+## The concept
+
+MDT defines 5 modular objects that can be used to build a simple deploy flow. These objects are:
+
+* Directory choosers - each of them defines how a deploy directory should be created, set as a working directory and, if necessary, removed on deploy failure.
+* Fetchers - each of them defines how the project contents should be fetched into the deploy directory.
+* Commands - each of them represents a single command executed in the deploy.
+* Command modifiers - each of them represents an expression that can be prepended to the command (like e.g. `bundle exec` from Ruby Bundler or environment variables). The way they are prepended is ultimately decided by the specific command.
+* Command groups - these are present only in the configuration and can be used to group together a set of other commands and command groups, describe it and add common parameters like command modifiers or make the whole group not fail the deploy.
+
+## Known modules
+
+* [mdt-dummy](https://github.com/Phitherek/mdt-dummy "mdt-dummy") - a module containing dummy implementations of each extensible MDT class. They can be used to skip a particular deployment step.
+
+## Contributing
+
+You can contribute to the development of MDT by submitting an issue or pull request. You can also extend MDT's capabilities by creating your own module in accordance with guidelines in MODULE_GUIDELINES.md and submitting it to RubyGems.

data/lib/mdt/command_modifiers/base.rb

@@ -2,10 +2,17 @@ require_relative '../errors/override_needed'
 require_relative '../modules/extensible'
 
 module MDT
+  # A module containing all command modifiers
   module CommandModifiers
+    # A base class for command modifiers
     class Base
       include MDT::Extensible
 
+      # A method that defines how to prepend command modifiers to commands. Raises MDT::Errors::OverrideNeeded.
+      # Arguments:
+      # * +key+ - a key identifier of a particular command modifier
+      # * +command+ - a command to apply command modifier on
+      # * +options+ - options for modifier as a Hash
       def prepend(key, command, options = {})
         raise MDT::Errors::OverrideNeeded.new('prepend')
       end

data/lib/mdt/commands/base.rb

@@ -2,10 +2,17 @@ require_relative '../errors/override_needed'
 require_relative '../modules/extensible'
 
 module MDT
+  # A module containing all commands
   module Commands
+    # A base class for commands
     class Base
       include MDT::Extensible
 
+      # A method that defines how to execute a command and how to apply command modifiers. Raises MDT::Errors::OverrideNeeded.
+      # Arguments:
+      # +key+ - a key identifier of a particular command
+      # +modifiers+ - an array of command modifier configurations - each configuration is a Hash that includes modifier type and modifier options
+      # +options+ - options for command as a Hash
       def execute(key, modifiers = [], options = {})
         raise MDT::Errors::OverrideNeeded.new('execute')
       end

data/lib/mdt/directory_choosers/base.rb

@@ -3,18 +3,32 @@ require_relative '../errors/override_needed'
 require_relative '../modules/extensible'
 
 module MDT
+  # A module containing all directory choosers
   module DirectoryChoosers
+    # A base class for directory choosers
     class Base
       include MDT::Extensible
 
+      # A method that defines how to create a deploy directory with directory choosers. Raises MDT::Errors::OverrideNeeded.
+      # Arguments:
+      # * +key+ - a key identifier of a particular directory chooser
+      # * +options+ - options for directory chooser as a Hash
       def mkdir(key, options = {})
         raise MDT::Errors::OverrideNeeded.new('mkdir')
       end
 
+      # A method that defines how to change the working directory to a deploy directory with directory choosers. Raises MDT::Errors::OverrideNeeded.
+      # Arguments:
+      # * +key+ - a key identifier of a particular directory chooser
+      # * +options+ - options for directory chooser as a Hash
       def cd(key, options = {})
         raise MDT::Errors::OverrideNeeded.new('cd')
       end
 
+      # A method that defines how to remove a deploy directory with directory choosers. Raises MDT::Errors::OverrideNeeded.
+      # Arguments:
+      # * +key+ - a key identifier of a particular directory chooser
+      # * +options+ - options for directory chooser as a Hash
       def rm(key, options = {})
         raise MDT::Errors::OverrideNeeded.new('rm')
       end

data/lib/mdt/errors/override_needed.rb

@@ -1,6 +1,11 @@
 module MDT
+  # A module containing all MDT errors
   module Errors
+    # An error thrown when a method in a base class needs to be overriden in a subclass.
     class OverrideNeeded < StandardError
+      # Initializes the error with the method key to be shown in error message.
+      # Arguments:
+      # * +method_key+ - the key of the method that needs to be overriden
       def initialize(method_key)
         super("Method #{method_key} must be overriden in a subclass!")
       end

data/lib/mdt/fetchers/base.rb

@@ -2,10 +2,16 @@ require_relative '../errors/override_needed'
 require_relative '../modules/extensible'
 
 module MDT
+  # A module containing all fetchers
   module Fetchers
+    # A base class for fetchers
     class Base
       include MDT::Extensible
 
+      # A method that defines how to fetch project contents to a deploy directory with fetchers. Raises MDT::Errors::OverrideNeeded.
+      # Arguments:
+      # * +key+ - a key identifier of a particular fetcher
+      # * +options+ - options for fetchers as a Hash
       def fetch(key, options ={})
         raise MDT::Errors::OverrideNeeded.new('fetch')
       end

data/lib/mdt/helpers/command.rb

@@ -1,7 +1,15 @@
 require_relative '../command_modifiers'
 module MDT
+  # A module containing all helper classes
   module Helpers
+    # A helper class to be used when implementing commands
     class Command
+      # Finds and applies command modifiers to a command using passed modifiers configuration.
+      # Arguments:
+      # * +command+ - a command or expression to prepend command modifiers to
+      # * +modifiers+ - an array of modifier configurations - each configuration is a Hash that includes the modifier type and modifier options
+      # Returns:
+      # * Modified command
       def self.apply_command_modifiers(command, modifiers)
         modifiers.each do |modifier_config|
           unless modifier_config.has_key?('type')

data/lib/mdt/helpers/runner.rb

@@ -1,7 +1,14 @@
 require_relative '../commands'
 module MDT
   module Helpers
+    # A helper class used in the MDT executable
     class Runner
+      # A method that processes an array of contents that includes configurations for commands and command groups.
+      # Arguments:
+      # +contents+ - an array of configurations for commands and command groups. Refer to example configuration file in the code repository for structure description
+      # +modifiers+ - an array of configurations for command modifiers that have to be applied to every command defined in +contents+
+      # Returns:
+      # * 1 on failure, otherwise 0
       def self.process_contents(contents, modifiers = [])
         failure = false
         contents.each do |elem|

data/lib/mdt/modules/extensible.rb

@@ -1,21 +1,32 @@
 module MDT
+  # A module to make the class a MDT base class
   module Extensible
+    # Adds needed class methods when included in a class.
+    # Arguments:
+    # * +klass+ - the class a module is being included in
     def self.included(klass)
       klass.class_eval do
+        # Stores the descendant classes.
         @descendants = []
+        # Defines a key that a subclass can be found by. Raises MDT::Errors::OverrideNeeded.
         def self.key
           raise MDT::Errors::OverrideNeeded.new('key')
         end
 
+        # Defines a set of subkeys that can be passed to class methods. Raises MDT::Errors::OverrideNeeded.
         def self.subkeys
           raise MDT::Errors::OverrideNeeded.new('subkeys')
         end
 
+        # Adds a subclass to the descendants variable when it is inherited and makes the list unique.
+        # Arguments
+        # * +subclass+ - a subclass that the class is inherited by.
         def self.inherited(subclass)
           @descendants << subclass
           @descendants.uniq!
         end
 
+        # Exposes descendants variable.
         def self.descendants
           @descendants
         end

data/lib/mdt/version.rb

@@ -1,5 +1,8 @@
+# Global MDT module
 module MDT
+  # A module referring specifically to mdt-core
   module Core
-    VERSION = '0.0.1'
+    # Version of the core gem
+    VERSION = '0.0.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mdt-core
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Phitherek_
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-28 00:00:00.000000000 Z
+date: 2018-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -30,8 +30,12 @@ email:
 executables:
 - mdt
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- MODULE_GUIDELINES.md
 files:
+- MODULE_GUIDELINES.md
+- README.md
 - bin/mdt
 - lib/mdt-core.rb
 - lib/mdt/command_modifiers.rb
@@ -52,9 +56,16 @@ files:
 homepage: https://github.com/Phitherek/mdt-core
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: http://www.rubydoc.info/github/Phitherek/mdt-core
+  source_code_uri: https://github.com/Phitherek/mdt-core
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--title"
+- MDT Core
+- "--main"
+- README.md
+- "--line-numbers"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement