Add Documentation for everything

.gitignore

@@ -2,7 +2,7 @@
 /.yardoc/
 /_yarddoc/
 /coverage/
-/doc/
+# /doc/
 /pkg/
 /spec/reports
 /tmp/

.rubocop.yml

@@ -12,6 +12,10 @@ Metrics/MethodLength:
   Max: 50
 Metrics/AbcSize:
   Max: 20
+  Exclude:
+    # mixin_config tends to overshoot, but is 
+    # still easily readable
+    - lib/miq_flow/mixin_config.rb
 
 Layout/SpaceBeforeBlockBraces:
   EnforcedStyle: no_space

.travis.yml

@@ -15,15 +15,14 @@ matrix:
       env: TAG=latest
     - name: "Hammer + Integration"
       rvm: 2.4
-      env: TAG=latest-hammer SUITE=integration
-
-before_install:
-  - script/prepare_manageiq.sh
-  - ruby -ryaml -e "c={'log_level'=>'debug', 'git'=>{'url'=>'https://github.com/ThomasBuchinger/automate-example'}}; puts c.to_yaml" > config.yaml
+      env: TAG=latest-hammer GIT_URL=https://github.com/ThomasBuchinger/automate-example
+      stage: integration
+      script:
+      - script/prepare_manageiq.sh
+      - rake install:local
+      - miq-flow deploy feature-1-f1 --provider docker --git-index 2
+      - ./script/verify_import.sh
 script:
   - bundle check # ManageIQ Container/Appliance needs to satisfy all dependencies
-  - rake install:local
-  - miq-flow deploy feature-1-f1 --provider docker
-  - ./script/verify_import.sh
   - bundle install --with development
   - bundle exec rake travis

CHANGELOG.md

@@ -1,21 +1,31 @@
 # Changelog
 
-## [Unreleased] ????-??-??
+## [unreleased] 2019-??-??
+### Added
+- Add user guide (#39)
+
+### Fixed
+- Updated outdated information in  README (#39)
+
+## [1.0.0-rc1] 2019-01-28
 ### Added
 - Initial commit
 - Added APACHE-2 LICENSE
 - Features:
-  - YAML based configuration
+  - Configuration sources:
+    - YAML files
+    - CLI parameter
+    - Environment variables 
   - Returns exit codes
   - Query ManageIQ API
   - Repository is cloned in the background and cleaned before the 
     program exists
   - Supports multiple Automate Domains
 - Availalbe Commands:
   - miq-flow deploy
-  - miq-flow inspect
-  - miq-flow list branches
-  - miq-flow list domains
+  - miq-flow branch inspect
+  - miq-flow branch list
+  - miq-flow domain list
 - Availalbe Providers:
   - provider_local (to be used on MIQ appliances)
   - provider_noop (does nothing)

README.md

@@ -1,46 +1,43 @@
 # ManageIQ Workflow Automate Importer
-[![Build Status](https://travis-ci.org/ThomasBuchinger/automate-gitflow.svg?branch=master)](https://travis-ci.org/ThomasBuchinger/automate-gitflow)
+[![Build Status](https://travis-ci.org/ThomasBuchinger/miq-flow.svg?branch=master)](https://travis-ci.org/ThomasBuchinger/miq-flow)
 
-This command line utility implements a git-based branching workflow on top of the default ManageIQ Automate Import scripts.
+This command line utility enables the use of git feature branches on top of the default ManageIQ Automate Export/Import scripts.
 
-Automation Engine is ManageIQ's way to integrate IT infrastructure into the wider Enterprise (e.g. CMDB, change management, billing, ...).
-It is common for ManageIQ deployments to have a shared DEV environment, because custom Automate Methods depend on:
+## The Problem
+ManageIQ handles multiple code trees (Automate Domains) using a priority based lookup, this limits the codebase to one `master` and one shared `develop` branch for all developers.
+
+At the same time it is common for ManageIQ deployments to have a shared DEV environment, as custom Automate Methods often depend on:
 * External services called via REST
-* Naming conventions in the virtual infrastructure 
 * Additional permissions (e.g. firewall clearing, administrative accounts, ...)
 
-# The Problem
-ManageIQ can handle multiple code trees (Automate Domains) using a priority based lookup, this limits the codebase to one `master` and one shared `develop` branch for all developers.
-To support mutliple feature branches, one has to:
-1. Find the files changed in a given feature branch
-1. Import only changed files, instead of everything
-
-miq-workflow is a command line tool, that uses the diff information in git to create partial domains and imports them in ManageIQ
+## How does miq-flow help?
+miq-flow uses the version history in git to enable "feature-domains", which avoid the lookup problem ([Details](doc/concept.md)).
 
-# How does miq-workflow help?
 * Multiple people can work on the same appliance at the same time (but not on the same method)
 * Promoting code is no longer a all-or-nothing decision
 * Pull-Requests and Commit-Squashing work the way you expect them to work
 * Code is cloned from a remote repository, if it is not already on the appliance
-* Manual changes on the WebUI are still possible (although a bit tricky)
+* Manual changes on the WebUI are still possible ([Details](doc/user_guide.md#release-the-code))
 
 # How do I use it?
-* Clone the repository onto your ManageIQ Appliance
-* Open `config.yaml` file and make sure you configure `git.url` and `miq.url` options
-* Run `./bin/miq-workflow deploy BRANCH` with the correct `--provider` option:
+* Download and install the `miq_flow` gem from [GitHub](https://github.com/ThomasBuchinger/miq-flow/releases)
+* Configure miq-flow:
+  * Use CLI parameter (see `miq-flow help`) or environment variables
+  * Download and edit the configuration file: `curl -o ~/.miqflow.yaml https://raw.githubusercontent.com/ThomasBuchinger/miq-flow/master/config.yaml`
+* Run `./bin/miq-flow deploy BRANCH` with the correct `--provider` option:
   * `local`: This provider assumes running on a ManageIQ Appliance and uses the evm:automate:import rake task (you want to use this one)
-  * `noop`: Preview what the script would do, without modifying ManageIQ
-  * `docker`: This Provider assumes a [manageiq/manageiq](https://hub.docker.com/r/manageiq/manageiq/) container running. (mostly for development)
+  * `noop`: Preview what the miq-flow would do, without modifying ManageIQ
+
+For additional instructions see the full [installation guide](doc/user_guide.md) or run miq-flow from [source](doc/developer.dm#setup-local-development)
 
 ## Commands
-See `./bin/miq-workflow` help for details. Basic Commands are: 
-* list git - lists a summary for each branch in git
-* list miq - lists Automate Domains found in ManageIQ
-* inspect _BRANCH_ - show details of a given branch
+See `miq-flow help` for details. Basic Commands are: 
+* branch list - lists a summary for each branch in git
+* branch inspect _BRANCH_ - show details of a given branch
+* domain list - lists Automate Domains found in ManageIQ
 * deploy _BRANCH_ - deploys the code in a feature-branch
-* (WIP) prune - remove feature-domains without a branch
 
 ## Notes
-* miq-workflow assumes to run on a ManageIQ appliance, since there is no way to remotely import Automate Domains
+* miq-flow assumes to run on a ManageIQ appliance, since there is no way to remotely import Automate Domains
 * Make sure you have [Rugged](https://github.com/libgit2/rugged), [RestClient](https://github.com/rest-client/rest-client) and [Thor](https://github.com/erikhuda/thor) installed (it is on the ManageIQ Appliances).
-* miq-workflow may checkout a different branch, when used with a local repository
+* miq-flow may checkout a different branch, when used with a local repository

config.yaml

@@ -1,7 +1,8 @@
 ---
 # Set logging level
+# If set to no_log, no log output will be generated
 # Default: info
-# Possible values: debug, info, warn, error, fatal
+# Possible values: debug, info, warn, error, fatal, no_log
 # log_level: info
 
 # git:
@@ -19,7 +20,17 @@
   #  Specify credentials for the repository.
   #  NOTE: only HTTP Authenication is supported
   #  user: someone
-  #  password: <TOKEN>
+  #  pashsword: <TOKEN>
+
+  # Branch naming scheme
+  # This configures the naming scheme for your git branches (if you use one)
+  # and how MiqFlow derives a name for the domains imported from that branch.
+  # The default configuration matches: TYPE-NAME-optional-description 
+  # 
+  # characters used to separate part of yu naming convention
+  # separators: [ '-', '/' ]
+  # index of the NAME part in your naming convention (starts with 0)
+  # index: 1
 
 # miq:
   # url: https://localhost/api

doc/concept.md

@@ -0,0 +1,2 @@
+# Concept
+> WIP: Please stand by

doc/developer.md

@@ -0,0 +1,31 @@
+# Developer Guide
+> WIP: Please stand by
+
+This is a collection of implementation details and internal decisions, which usually do not concern the average user
+
+## Setup local development
+* install docker
+* install ruby & bundler
+* clone the repo
+* bundle install --with development
+* ./script/prepare-manageiq
+* use --provider docker
+
+## Import Methods
+### Partial Import
+
+### igortiunov's Automate scoped Import
+
+
+## Providers
+### No API for import yet :(
+
+
+## (optional) build libgit2 with ssh support?
+
+## Documentation Guidelines
+### Refering to entities in guides
+* `we` the miq-flow project and people working on it
+* `you` the user reading the guide
+* ManageIQ specific things (e.g. Automate) start with a capital letter
+

doc/reference.md

@@ -0,0 +1,47 @@
+# Reference
+> WIP: Please stand by
+
+## Motivation
+### starting point?
+
+### Problems
+* single DEV -> disabling in-progress-code
+* "disabled" in-progess code still makes it to PROD
+
+### Benefits
+* local development
+* PRs work
+* (for large codebases) bettter overview over changes
+* contributions over git
+* source of truth in git
+* possible to use git domains
+
+
+## Proxy Support
+Support for operating system level proxy has to be compiled in the git library (`libgit2`). This work is ongoing upstream and depends on the exact version numbers involved. Currently only Hammer seems to support Proxies.
+* Hammer: Configure `http_proxy` ENV variable. (`HTTP_PROXY`, `HTTPS_PROXY` and `https_proxy` variables seem no to be honored)
+* Gaprindashvili: not supported
+* Fine: not supported
+
+## SSH Support
+Support for SSH as transport protocol is not available on ManageIQ, as it has to be compiled in the git library (`libgit2`).
+
+## Confiuration Options
+### Use a local repository
+
+## Provider
+Technically Miq-Flow also needs know, how to access to ManageIQ's `evm:automate:import` rake task, in addition to the git repository.  
+Since we are running on the appliance and the only real provider is local, we do not need to configure it
+
+## Naming conventions
+Miq-Flow uses a part of the branch name as name for the Automate domains it creates. Branch names in git often follow a naming convention (e.g. `<type>-<name-or-ref>-<description>`), which are long and/or contain illegal characters for Automate domains. Therefore miq-flow renames it's Automate domains as `feat_<NAME>_<BASE-NAME>`. 
+
+In case you use any other naming convention, miq-flow uses a simple index to figure out which part is the `NAME`. Configurable via the `git.seperators` and `git.index` parameters 
+
+> These automatic names can be overwritten by a command line flag. But some features in the future may rely on this automatic naming to match Automate domains in ManageIQ the branches in git.
+
+## Glossary
+* `Automate code` general term for code written for ManageIQ's Automation Engine
+* `base domain` Automate domain for "released" code. In git term this would correspond to the master branch
+* `feature domain` Automate domain for a single feature. In-progress code, that contains only the subset of methods that were changed to implement a feature.
+