README.md in noe-1.0.0 vs README.md in noe-1.1.0

- old
+ new

@@ -1,59 +1,124 @@ # Noe - A simple and extensible project generator -Noe helps development by providing support for project templates and instantiation. +Noe is a tool that generates projects from predefined skeletons (aka project/application +templates). Skeletons are designed for building specific products (a ruby library, a static +or dynamic web site, ...). Noe instantiates them and helps you maintaining your product +via meta-information provided by a .noespec yaml file. -## Why? +Noe comes bundled with a skeleton for creating and maintaining a ruby gem. This skeleton +is written and maintained to follow ruby best practices and may also be tuned for your own +needs. Read more about it and related projects as well as the underlying philosophy in the +sections below. -I'm pretty sure I have seen announcements for similar projects on ruby-lang in the past, -but I could not find them anymore... so I started mine. Please let me know alternatives -and I'll add them below: - -See also: - -* ... - -Other reasons: - -* Noe is agnostic: it does not make any assumption about project semantics -* Noe does not restrict itself to generation of ruby projects -* Noe is not required at runtime: once your project is generated you're done -* I don't like magic - ## Getting started [sudo] gem install noe [noe --help] [noe help install] noe install -Have a loot at ~/.noerc and ~/.noe for configuration and a default ruby -template. - -## Usage summary +Have a loot at ~/.noerc and ~/.noe for configuration and a default ruby template. To +instantiate a ruby project simply execute the following commands in turn: -Maintain your templates under ~/.noe (or what you provided at installation time). Have a -look at github to find xxx.noe projects to find well-designed/documented templates for -specific needs. - -To create a fresh new project: - - # Given a template xxx under ~/.noe/xxx - noe create --template=xxx foo + # Given a template ruby under ~/.noe/ruby, install by default + noe prepare --template=ruby foo cd foo # Edit the template configuration foo/foo.noespec edit foo/foo.noespec # Launch template instantiation noe go -That's it! But also have a look at 'noe help create' and 'not help go' for additional +That's it! But also have a look at 'noe help prepare' and 'not help go' for additional options. -## About templates +## Philosophy +Noe is designed to follow a certain number of good principles and helps you following +them as well. + +### Separation of concerns + +Noe maintains a strong separation of concerns. In particular one has to make the distinction +between a) Noe itself, b) a skeleton and c) an instantiated product. This fact has two +main consequences: + +* Noe itself **is not dedicated to specific products** (like a ruby library). Even if Noe + comes bundled with a default skeleton for ruby projects, writing skeletons for something + else should not be a problem. In other words, Noe itself is agnostic: the semantics of + generated products is the secret of the skeleton, under the responsibility of it's + maintainer. + +* Noe **should not be a runtime dependency** of the product. Good skeletons maintain this + separation. As an example the default ruby skeleton is strictly independent of Noe itself. + Principles discussed below explain why this is important. + +### Master the tools YOU use + +The separation of concerns described previously also drives what you have to learn and what +tools you have to master: + +* As an ordinary Noe user (vs. skeleton maintainer) and because Noe itself (unlike skeletons + is project agnostic, you only have to know **basic Noe commands** (see 'noe --help') and + should never have to study Noe's API and internals. In contrast, you have to **master the + tools and best practices of your product's ecosystem**. A good skeleton should help you + along this task. As an example, the default ruby skeleton is fully documented to help you + gaining understanding of ***rake*, *spec*, *yard*, *bundler*** and so on but **not noe + itself**. + +* This explains why Noe itself is not a runtime dependency. Using a particular skeleton + already means learning a lot, at least in the long run (see the section about Magic below). + Noe avoids interfering with generated products to avoid making the learning curve even + worse. + +* Being a skeleton creator/maintainer is another story of course. To write a skeleton you'll + also have to learn **Noe's API and internals**. To write a good/reusable one, you'll + certainly have to **master the full ecosystem and best practices of the targetted product**, + which is a good opportunity for learning and sharing it! + +### Magic Only If Flexible + +"Don't Repeat Yourself" and "Convention over Configuration" are certainly good principles. +However tuning, configuration and options exist, are useful and should certainly not be +hidden to the user. Instead configuration and options should come with default values, +and should be fully documented. Providing magic is great if there is a user-centric way +(in contrast to a developer one) of understanding and controlling the magic and underlying +assumptions. + +As an example, the default ruby template comes with some magic: you can create a project +and immediately invoke 'rake test', 'rake yard', ... and not investigating further. You +can also have a look at the _tasks_ folder to understand and control the rake tasks that +your project will use... In fact, you **must** investigate: the generated product is yours, +not mine and YOU have to master your build chain! + +## Ruby skeleton and Related projects + +Noe is inspired by existing projects, mostly from the ruby community. In particular, the +default ruby template has been heavily influenced by the projects below as well as feedback +of their authors: + +* [hoe](http://seattlerb.rubyforge.org/hoe/), Ryan Davis and Eric Hodel +* [echoe](https://github.com/fauna/echoe), Evan Weaver +* [bones](https://github.com/TwP/bones), Tim Pease + +These projects help you generating and maintaining ruby projects (generally gem libraries, +in fact). All provide powerful tools that supports you along the different steps of your +ruby software lifecycle (creating, testing, releasing, announcing, and so on.). They mostly +differ in the way you can tune/configure the generated project for specific needs. + +These projects differ from the Ruby skeleton proposed by Noe in that they use a control +approach (rake tasks installed in your project via a development/runtime dependency) while +Noe uses a generative approach (the generated ruby project and rake tasks do not depend on +Noe at all). + +You'll find more information about the Noe's ruby skeleton in it's own +[README](https://github.com/blambeau/noe/blob/master/templates/ruby/README.md). + +## Short guide for template maintainers + Under ~/.noe, a valid template folder (say xxx) has the following structure xxx # Template name README(.md|.txt|...) # Information about the template and it's usage CHANGELOG(.md|.txt|...) # Change information @@ -61,20 +126,21 @@ src # Source folder, contains files to be instantiated ... # [everything that will be instantiated] ### noespec.yaml -The noespec.yaml file of a template is used to formally describe the template. When a project -(say foo) is created (see 'noe create') using a template (say ruby) the file -~/.noe/ruby/noespec.yaml is used to generate foo/foo.noespec. The later is then used by -'noe go' to instantiate the project. +The noespec.yaml file of a template is used to formally describe the template. When a +project (say foo) is created (see 'noe prepare') using a template (say ruby) the file +~/.noe/ruby/noespec.yaml is used to generate foo/foo.noespec. The later is then used +by 'noe go' to instantiate the project. The noespec.yaml file should ressemble something like this: # DO NOT TOUCH 'name' entry and specify the other template-info: name: !{template_name} + summary: ... description: ... version: ... author: ... # @@ -88,20 +154,20 @@ Have a look at ~/.noe/ruby/noespec.yaml and ~/.noe/ruby/src for an example. ### Instantiation process -The instantiation process is really simple. Given the variables described in the noespec.yaml -file (for which values are specified in your .noespec file) templates can use the following -meta-constructions: +The instantiation process is really simple. Given the variables described in the +noespec.yaml file (for which values are specified in your .noespec file) templates +can use the following meta-constructions: -* Template files and directories containing `__variable__` in their name are automatically +* Template files and directories containing `__variable__` in their name are automatically renamed (`__variable__` is replaced by the corresponding value). -* All template files are instantiated by [wlang](https://github.com/blambeau/wlang). You don't - have to know wlang in depth. You simply have to know that `!{ruby_expression}` in a file is - replaced by the expression evaluation. Variables are automatically in scope of such expressions, - so that `!{variable}` is replaced by its value. +* All template files are instantiated by [wlang](https://github.com/blambeau/wlang). You + don't have to know wlang in depth. You simply have to know that `!{ruby_expression}` in + a file is replaced by the expression evaluation. Variables are automatically in scope + of such expressions, so that `!{variable}` is replaced by its value. ## Contributing Fork Noe on github! I'm particularly interested in the following enhancements: @@ -109,9 +175,9 @@ * Enhance the default ruby template, but remember "documentation matters, not magic!" * Add support for other generators than _wlang_ * Add support for multi-generated files from arrays in .noespec files * ... -If you think that your template is worth considering for (ruby, rails, js, latex, or anything -else) please let me known and I'll add it to the list below. +If you think that your template is worth considering for (ruby, rails, js, latex, or +anything else) please let me known and I'll add it to the list below. * ...