katapult 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e300dbf1f253287be637c885c6d9c42ee23272c4e1259c1608194c744433c6d
-  data.tar.gz: 92e3a0218852ab314dee4de60e3e753140795031310eaa2bc90700a2b5113666
+  metadata.gz: da5e56a99ddf91445aed9d85f07c27e0fba63090536dcc13724b73be1d64c0fb
+  data.tar.gz: dc2a5956825e7624c9c6942a3b94cfcc028370e553ca14178847a6d87f22f625
 SHA512:
-  metadata.gz: 99f96cfcd585edc21231c1d3c0d2778bbc2def2f60facdb4ffdf56f64d8498ee34eb3b6c6f751a00768a1bdc0fc690bbca3a871cf373c499c53e4a21d968171d
-  data.tar.gz: 48655800af8a0439cc7738c6e455e03589e6d071fe25177b652b342fdea0ce1268e1c9f88974fa21f284f64961985d8706e6888c8438740e277e27bf85a20456
+  metadata.gz: 24ae3501b48b18939d4fe22f4236976bf249a5af74878933bcbc5385c8fe10e0032258205fca340a8d2a1a01387bdf232ab458003facc5948e5ceab19d6f1baa
+  data.tar.gz: 3802474a2ae1a8818b076d2aa3109b91de0c871ff728086baf0ad6a82af07a4ff75ab6399c60888abcd5e61412f978dccde60c8fed72614cea3fd8941a0529cd

data/.gitignore

@@ -4,6 +4,7 @@
 .config
 .yardoc
 Gemfile.lock
+!lib/generators/katapult/basics/templates/Gemfile.lock
 InstalledFiles
 _yardoc
 coverage

data/CHANGELOG.md

@@ -1,30 +1,52 @@
 # Changelog
 
-## 0.4.0 on 2018-01-15
+All notable changes to this project will be documented in this file. Changes are
+segmented into: New Features / Improvements.
 
-### Features
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+
+## 0.5.0
+
+### New Features
+- Deployment ready for Opscomplete
+- Copying view and controller templates over to target application via new
+  command `katapult template` or generator `katapult:templates`.
+
+### Improvements
+- Generating a fixed Gemfile.lock. Run `bundle update` after code generation to
+  update all gems to recent versions.
+- Better deployment with Webpack
+- Navigation only rendered if requested
+- "Usage" section in README rewritten
+- Some minor fixes
+
+## 0.4.1 - 2018-02-16
+
+### Improvements
+- Changed CHANGELOG to satisfy [How to write a good changelog](https://makandracards.com/makandra/54223-how-to-write-a-good-changelog) format
+- Minor fixes and improvements
+
+## 0.4.0 - 2018-01-15
+
+### New Features
 - Support for has_many/belongs_to associations
 - Create a project README
 - New CHANGELOG
-
-### Fixes
 - Models now inherit from `ApplicationRecord`
 
+## 0.3.0 2018-01-11
 
-## 0.3.0 on 2018-01-11
-
-### Features
+### New Features
 - Generating a Rails 5.1.4 app on Ruby 2.5.0
 - Dropped asset pipeline in favor of Webpacker
-- The generated application now has a sleek, simple design based on Bootstrap
 - Employing [Unpoly](https://unpoly.com)
 - New DSL command `crud` for creating Model plus WebUI
 - The generated application model is now a transformable example of katapult's features
-
-### Development improvements
+- The generated application now has a sleek, simple design based on Bootstrap
 - Add katapult update script
+
+### Improvements
 - Speed up tests (now running in about 9 min)
 - Improve development workflow (see README)
 - No bundler issues in tests any more
-
-See [all changes](https://github.com/makandra/katapult/compare/v0.2.0...v0.3.0).

data/README.md

@@ -1,100 +1,132 @@
-# Katapult
+# Katapult 0.4.1
+Generating a Rails 5.1.4 app on Ruby 2.5.0.
 
 <img src="katapult.png" width="200px" align="right" />
 
 
-`Katapult` is a kickstart generator for Rails applications. It creates new Rails
-applications with [lots of pre-configuration](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
+Katapult is a kickstart generator for Rails. It prepares a new
+application with [lots of pre-configuration](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
 and offers [makandra-flavored](https://leanpub.com/growing-rails) code
-generation from an application model. These two features significally speed up
-the initial phase of a Rails project by doing in minutes what otherwise would
-cost you weeks.
-After modeling your application, which typically takes about an hour, you can
-instantly start implementing the meat of your application.
-
-`Katapult` only supports a single Ruby and Rails version, currently it's Rails
-5.1.4 and Ruby 2.5.0.
+generation from an application model. This significantly speeds up the initial
+phase of Rails development by doing in minutes what would cost you weeks. When
+Katapult has finished, you can instantly start implementing the interesting
+parts of your application.
 
 
 ## Prerequisites
 
 Katapult uses *PostgreSQL* as database, so you'll need to install that upfront.
-Also, it drops the asset pipeline in favor of *Webpacker*, so you'll need Node
-and Yarn (see <https://makandracards.com/makandra/47477>).
+Also, it drops the Rails asset pipeline in favor of *Webpacker*, so you'll need
+*Node* and *Yarn* (see <https://makandracards.com/makandra/47477>).
 
-Also, it requires the *Bundler* and *Rake* Ruby gems, which are probably already
-installed on your system.
+The required *Ruby* version is 2.5.0. You'll need the *Bundler* and *Rake* gems,
+which are probably already installed on your system.
 
+When you're using the `katapult` binary (you should), you'll also need *Git*.
 
-## Installation
 
-Install the `katapult` gem with
+## Installation
 
     gem install katapult
 
-If you intend to extend an existing application, add it to the development group
-in your Gemfile.
-
 
 ## Usage
 
-`katapult` does two distinct things for you:
+There are two usage scenarios for Katapult:
 
-1. It creates a new Rails application, set up with many standard gems, snippets,
-   useful configuration, databases, testing libraries etc.
-2. It generates code from an application model, i.e. it creates models and
-   views, controllers, styles etc. 
+1. Starting a fresh Rails application
+2. Extending an existing Rails application
 
-You may use both or only one of them. Read on for details.
+Choose your use case and read on below.
 
 
-## 1) Creating a new Rails application
+## Starting a fresh Rails application
 
-Run the following command:
+To create a new Rails application with Katapult, run the following command:
 
     katapult new $APPLICATION_NAME
 
-This will create a new Rails application and prepare it in more than 20 steps.
-Read the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
-for details: Its methods are executed one-by-one, while the method names are a
-description of what they do.
+This will create a new Rails application, prepared and configured: bundled,
+database set up, RSpec, Cucumber and Capistrano installed and much more.
+Please read the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
+for details (its methods are executed one-by-one from top to bottom).
+
+When Katapult is done, you will find a default application model in
+`lib/katapult/application_model.rb`. It contains a full example of Katapult's
+DSL that you can use as an inspiration for creating your own application model.
+
+Next, check the templates in `lib/templates/katapult`. They will be used
+to generate the corresponding files, e.g. HAML views. Please modify the templates
+to match your requirements. (Actually, you can customize much more templates.
+Each template in Katapult's `lib/generators/katapult/<generator>/templates/` can
+be overridden with a file at `lib/templates/katapult/<generator>/` in your
+application.)
+
+When your application model and the templates are ready, let Katapult generate
+your code:
+
+    katapult fire
+
+This will create models, migrations, views, styles, controllers, routes,
+Cucumber features, specs, factories and more. It will also commit the results
+and migrate the database.
+
+When this is done, your application is ready to use! Start a development
+server and try it out.
+
+
+## Extending an existing Rails application
 
-### Alternative: Using Katapult in an existing Rails application
-`katapult` expects a fresh application (which it would usually generate itself).
-If you have an existing Rails application, you *may* use `katapult`, but be
-warned: it is not designed to respect existing files, although it will usually
-ask before overwriting something.
+You can use Katapult for code generation in an existing application as well.
 
-After adding it to the Gemfile, run the basics generator manually:
+First, add Katapult to the development group in your Gemfile:
+```
+  gem 'katapult'
+```
 
-    bin/rails generate katapult:basics
+Next, generate the default application model:
 
+```
+bundle exec rails generate katapult:app_model
+```
 
-## 2) Generating code from an application model
+You'll find the application model at `lib/katapult/application_model.rb`. It
+contains a full example of Katapult's features: Use it as an inspiration for
+modeling your own application. (When you're used to the application model DSL,
+you don't need to generate the default model. Just create a Ruby file and start
+modeling.)
 
-After running `katapult new`, you will find a default application model in
- `lib/katapult/application_model.rb`. It contains a full example of `katapult`'s
-features that you should replace with _your_ application model.
+Next, copy Katapult's template files to your application:
 
-When you are done, transform the model using:
+```
+katapult templates
+```
 
-    katapult fire [path/to/application_model]
+This will copy some of Katapult's file templates to `lib/templates/katapult`.
+Modify them, especially the view templates, to match the current state of your
+application. You can customize even more templates, see the "Starting …" section
+above.
 
-The path is optional and only needs to be specified when you've renamed the
-application model file. Note that you may well use separate model files for
-separate runs.
+When model and templates are ready, trigger code generation with:
 
-See an overview of the DSL below. The respective sections hold examples of what
-options are available to each element. For details, dive into
-`lib/generators/katapult` where all generators are stored. The method names
-of a generator tell what it does.
+```
+katapult fire path/to/your_model.rb
+```
 
-### Generic DSL syntax example
-The DSL consists of _elements_, e.g. `Model` or `WebUI`. Each `katapult` element
-has the following syntax, taking a name, options, and a block:
 
-    element_type 'name', options: 'example' do |element|
-      element.some_method
+## DSL reference
+
+Below you find an overview of the application model DSL. The respective sections
+hold examples of what options are available to each element. For details, dive
+into the respective generator at `lib/generators/katapult/*/*_generator.rb`. The
+method names of a generator tell what it does.
+
+### Crud
+Shortcut for creating a model together with a WebUI with CRUD actions. The block
+is passed the model instance.
+
+    crud 'Customer' do |customer|
+      # customer.attr :name
     end
 
 
@@ -115,7 +147,7 @@ needed.
     # Default type :string
     model.attr :name
     
-    # Inferred type :email (when attr name matches /email/)
+    # Inferred type :email (attribute name matches /email/)
     model.attr :email
 
     # Inferred type :password. Password fields are rendered as password_field in
@@ -139,9 +171,9 @@ needed.
     model.attr :avoid, type: :plain_json # PostgreSQL "json"
 
 
-### Association
-Defined on Model; takes the name of another model just like you called it in the
-model. Adds a foreign key attribute to the model and `belongs_to`/`has_many`
+#### Association
+Defined on Model; takes the name of another model (just as you called it in the
+application model). Adds a foreign key attribute to the model and `belongs_to`/`has_many`
 calls to the respective models.
 
     model 'Customer' do |customer|
@@ -157,7 +189,6 @@ passing Cucumber feature.
 
     web_ui 'Customer', model: 'User' do |web_ui|
       web_ui.crud # Create all the standard rails actions
-
       # web_ui.action :custom etc, see Action element
     end
 
@@ -180,13 +211,6 @@ and a route as needed.
     web_ui.action :custom_action, method: :post, scope: :member
     web_ui.action :other_action, method: :get, scope: :collection
     
-### Crud
-Shortcut for creating a model together with a WebUI with CRUD actions.
-
-    crud 'Customer' do |customer|
-      customer.attr :name
-    end
-
 
 ### Navigation
 Generates a main menu with links to the index pages of all WebUIs.
@@ -206,65 +230,78 @@ Rails, including Clearance mails like password reset requests.
 
 ## Development
 
-### Getting started + continuing development
+### Getting started
 `Katapult` is tested with [RSpec](http://rspec.info/) and
 [Cucumber](https://cucumber.io/) + [Aruba](https://github.com/cucumber/aruba)
-([API-Doc](http://www.rubydoc.info/github/cucumber/aruba/master/)).
+([API documentation](http://www.rubydoc.info/github/cucumber/aruba/master/)).
 
-For its full-stack integration tests, `katapult` requires a PostgreSQL account.
+For its full-stack integration tests, Katapult requires a PostgreSQL account.
 Create a dedicated account on your local PostgreSQL server:
 
     $> sudo -u postgres psql
     postgres=# CREATE ROLE katapult WITH createdb LOGIN;
 
-Whenever you start working on `katapult`, you should run `script/update`, which
+
+### Continuing Development
+Whenever you start working on Katapult, you should run `script/update`, which
 will guide you through a quick update process.
 
 ### Architecture
-`katapult` is roughly split into three parts: the `katapult` binary in bin/,
+Katapult's code is roughly split into three parts: the `katapult` binary in bin/,
 the model in lib/katapult/ and the generators in lib/generators. Also, there
-is a script/ directory that holds some scripts to ease development. It is not
-part of the `katapult` gem, however.
-
-The generators of `katapult` base on the `rails/generators` you probably know
-from generating migration files or scaffolds; however, it lifts their usage on a
-new level by invoking generators programmatically with a "model object". Instead
-of plain text input, the `katapult` generators can explore the whole application
-model. They are all to be run from within a Rails application.
-
-There are three base generators that can be considered the next-lower level API
-of `katapult`:
-
-- `basics` generator: Enhances a pristine Rails app with all of the basic
-  configuration `katapult` brings.
-- `app_model` generator: Installs a boilerplate application model that serves as
-  a starting point for modeling your own application.
-- `transform` generator: Parses the application model into an internal
+is a script/ directory that holds some scripts to simplify development. It is not
+included in the `katapult` gem.
+
+The generators of Katapult extend the `rails/generators` you probably know
+from generating migration files or scaffolds. However, Katapult lifts them on a
+higher level by passing them a model object instead
+of plain text arguments. This way, the Katapult generators can explore the whole
+application model and are not restricted to a few strings they've been given.
+
+There are a few "public" Rails generators. They can be considered the next API
+level after the `katapult` binary:
+
+- `katapult:basics`: Enhances a pristine Rails app with all of the
+  basic configuration.
+- `katapult:app_model`: Installs a boilerplate application model that
+  serves as a starting point for modeling an application.
+- `katapult:templates`: Copies some generator templates to the target
+  application.
+- `katapult:transform`: Parses the application model into an internal
   representation, which will be turned into code by all the other generators.
 
-Note that the `katapult` binary is the only Rails-independent part of Katapult;
-everything else runs in the context of the Rails appplication.
+Note that the `katapult` binary is the only Rails-independent part of Katapult.
+Everything else runs in the context of the Rails application.
 
 ### Suggested workflow
-When adding a feature to `katapult`, it will usually take you some time to
+When adding a feature to Katapult, it will usually take you some time to
 figure out how exactly the generated code should look like. You'll be switching
-between `katapult`'s tests, its generators and the generated code.
+between Katapult's tests, its generators and the generated code.
 
-Here's a the suggested process:
+Here's a process for building larger code generation features:
 
-1) Run a scenario (create one if needed)
-2) Tag that scenario with @no-clobber. This will leave the generated test app
-   untouched in subsequent test runs.
+1) **Start with a test:** Create a Cucumber scenario that creates and transforms
+   an application model. Also, write a first draft of the code that generates
+   what you expect.
+2) Run your scenario. This will transform your test application model.
 3) Make a commit inside the generated test application, so you'll have a clean
    working directory: `script/kta git add --all && script/kta git commit -m 'x'`
-4) Modify the test app as needed. Boot a development server with
-   `script/kta rails s` if you like.
-5) Re-run the @no-clobber scenario (modify it as needed) until test and test app
-   meet the expectations.
-6) Now look at the git diff in the test app and model everything with katapult's
-   generators.
-7) Remove the @no-clobber tag and run the scenario normally to see if it's still
-   green. Remember to stop the development server first.
+4) **Modify the generated code** inside the generated test application until it
+   meets your expectations. If you like, boot a development server with
+   `script/kta rails s`.
+5) **Finish your test:** Once you've figured how the generated code should look
+   like, it's time to write steps that test it. For this purpose, tag your
+   scenario with @no-clobber and comment out the model transformation step. This
+   will leave the generated test app untouched in subsequent test runs, so you
+   will be able to run your scenario repeatedly, without losing what you've
+   built, until you have covered every change. Use `git diff` in the test app to
+   see your changes.
+6) **Write code:** When you've completed your scenario, write the code that
+   generates what is needed to satisfy the test.
+7) Remove the @no-clobber tag and uncomment the transformation step. Stop the
+   development server if you've started one.
+8) Run your scenario normally and iterate over your code generation code until
+   your scenario is green.
 
 ### Guidelines
 Please respect the following guidelines during development:
@@ -272,21 +309,24 @@ Please respect the following guidelines during development:
 - The application model should be order-agnostic. There is a #prepare_render
   method in `ApplicationModel` for things that need to happen between parsing
   and rendering the application model.
+- Transformation should be idempotent: it should be possible to generate the
+  application model over and over again without crashing or breaking things.
 
 ### Debugging
-Add the `@announce-output` tag to `katapult` features in order to have any output
+Add the `@announce-output` tag to Katapult scenarios in order to have output
 logged to your terminal. Note that each step will print all output to date, so
 you will see things multiple times.
 
 To precisely debug errors occurring _inside_ the generated application, use
-`script/kta`. You could also just cd to the test app directory, but since it is
-destroyed between test runs, you'd need to `cd ../../aruba/katapult_test_app`
-after each test.
+`script/kta`. It is a helper script that will execute whatever command you pass
+it, but in the directory of the generated application. While you could cd to the
+test app and run your command there, you'd need to `cd ../../aruba/katapult_test_app`
+between test runs, because the tmp/aruba directory gets wiped before each test.
 
 When fixing issues in the generated app, make a commit in the app first. When
 you've fixed it, the diff will show you what you need to port back to katapult.
 
-### Typical issues
+#### Typical issues
 Be sure to check this list when you encounter strange issues during development.
 
 - Spring was running in a directory that does not exist any more. This will
@@ -295,10 +335,10 @@ Be sure to check this list when you encounter strange issues during development.
 - An outdated Rails application in `tmp/cached_*`
 - Timeout error because of a script waiting for user input
 
-### Fast tests
+#### Fast tests
 Generating basics and transforming the application model take quite some time
 (about 20s), because it boots the Rails application, resolves Yarn dependencies
-and migrates databases. To speed that up, `katapult` tests cache prepared Rails
+and migrates databases. To speed that up, Katapult tests cache prepared Rails
 applications in tmp/.
 
 When debugging test suite speed, `bundle exec cucumber --format usage` is your