Skip to content

Latest commit

 

History

History
145 lines (111 loc) · 3.63 KB

4.0-Development-Subprojects.md

File metadata and controls

145 lines (111 loc) · 3.63 KB

NOTE: This document is outdated. It does not reflect the current nanoc 4.x development work.

Starting in nanoc 4.0, nanoc will be split in several subprojects. Each filter, helper, … will have its own repository, as well as each frontend (currently only the commandline frontend). This is done for a few reasons:

  1. It makes passing on maintainership easier. Developers can take over a subproject without requiring push access to the main project, or having to send pull requests for every change.

  2. It improves the usefulness of automated tests. Automated tests become more useful because it becomes easier to pinpoint a failure.

  3. It decouples the plugin release cycle from the nanoc release cycle. A fix for a subproject can go out immediately, without waiting for a release of the main project. Likewise, a backwards-incompatible version of a subproject can be released without impacting the main project.

Notes

  • The filesystem data source will still be part of core. Ideally, it could be moved out, but a lot of tests in core depend on the filesystem data source, and cleaning that up is a lot of (unecessary) work.

  • For the same reason, the erb filter is still part of core as well.

Renaming and removing helpers

  • Get rid of the text helper. It is tiny, incomplete and buggy.
  • Ensure helper names end with -ing. This means
    • html_escaping, not html_escape
    • linking, not link_to

Directory structure

Main project

  • lib/
    • nanoc/
      • core/
        • entities/
          • …
        • version.rb
    • nanoc-core.rb

Subproject

An example of the AsciiDoc filter:

  • lib/
    • nanoc/
      • asciidoc/
        • filter.rb
        • version.rb
    • nanoc-asciidoc.rb

Loading plugins

  • Filters: Rely on Bundler (Bundler.require(:default)) to load everything.
  • Helpers: Rely on Bundler (Bundler.require(:default)) to load everything.
  • Commands: Plugin must depend on nanoc-cli and load commands the normal way.

Versioning

  • nanoc-core has lib/nanoc/core/version.rb, which defines Nanoc::VERSION.
  • nanoc has lib/nanoc/version.rb, which requires nanoc/core/version.
  • nanoc-cli has no lib/nanoc-cli/version.rb and no Nanoc::CLI::VERSION.

Projects

Meta-gems

  • nanoc, depending on
    • nanoc-core
    • nanoc-cli
    • nanoc-kramdown
    • nanoc-haml
    • nanoc-sass
    • nanoc-blogging
    • nanoc-html_escape
    • nanoc-link_to
    • nanoc-rendering
  • nanoc-powerpack, depending on EVERYTHING

Basic components

  • nanoc-core
  • nanoc-cli

Plugins

  • nanoc-check - Also includes the CLI command.
  • nanoc-deploy - Also includes the CLI command.

Checks

  • nanoc-html_check
  • nanoc-css_check
  • nanoc-external_links_check
  • nanoc-internal_links_check
  • nanoc-stale_check

Deployers

  • nanoc-rsync_deployer
  • nanoc-fog_deployer

Filters

  • nanoc-asciidoc
  • nanoc-bluecloth
  • nanoc-coffeescript
  • nanoc-colorize_syntax
  • nanoc-erubis
  • nanoc-haml
  • nanoc-handlebars
  • nanoc-kramdown
  • nanoc-less
  • nanoc-maruku
  • nanoc-mustache
  • nanoc-pandoc
  • nanoc-rainpress
  • nanoc-rdiscount
  • nanoc-rdoc
  • nanoc-redcarpet
  • nanoc-redcloth
  • nanoc-relativize_paths
  • nanoc-rubypants
  • nanoc-sass
  • nanoc-slim
  • nanoc-typogruby
  • nanoc-uglify_js
  • nanoc-xsl
  • nanoc-yui_compressor

Helpers

  • nanoc-blogging
  • nanoc-breadcrumbs
  • nanoc-capturing
  • nanoc-filtering
  • nanoc-html_escape
  • nanoc-link_to
  • nanoc-rendering
  • nanoc-tagging
  • nanoc-text
  • nanoc-xml_sitemap