Towards Arcturus: How Can We Have Our Own Flavor

UPDATE: We now have our own flavor. See OS ACE and a the gem.

We want to spin up our own aurora variant based on the Polaris flavor. How does the workflow work, and how can we implement our own?

Aurora Basic Setup

@see Aurora Installation Docs

Steps from scratch, including the duh steps:

1. Install Drupal.
2. Install Aurora.
3. Install Magic Module.
4. Install HTML5 Tools.
5. Install Compass+Sass.
6. Install the Aurora Compass Extension (ACE): gem install compass-aurora.

What's with ACE?

Installing the gem goes out to rubygems.org and finds the compass-aurora gem. The source code for this gem is at https://github.com/Snugug/Aurora. Installing the gem places the code into your gem enviroment, i.e. /var/lib/gems/1.9.1 or similar.

Spinning Up A Subtheme

@see Aurora Subtheme Docs

There are currently 3 flavors of Aurora subthemes: Aurora, Corona, and Polaris. We create an aurora subtheme as a Polaris flavor with the following command:

compass create arcturus -r aurora --using aurora/polaris

Which gives the following output:

directory arcturus/ 
directory arcturus/sass/ 
directory arcturus/sass/partials/ 
directory arcturus/sass/partials/global/ 
directory arcturus/sass/partials/layouts/ 
directory arcturus/sass/partials/modules/ 
directory arcturus/sass/partials/states/ 
directory arcturus/sass/partials/styleguide/ 
directory arcturus/stylesheets/ 
directory arcturus/templates/ 
   create arcturus/config.rb 
   create arcturus/sass/README.md 
   create arcturus/sass/partials/README.md 
   create arcturus/templates/README.md 
   create arcturus/arcturus.info 
   create arcturus/template.php 
   create arcturus/sass/print.scss 
   create arcturus/sass/partials/states/_states.scss 
   create arcturus/sass/partials/styleguide/_style-guide.scss 
   create arcturus/sass/partials/global/_base.scss 
   create arcturus/sass/partials/layouts/_layouts.scss 
   create arcturus/sass/partials/modules/_modules.scss 
   create arcturus/sass/style.scss 
   create arcturus/sass/partials/global/_variables.scss 
   create arcturus/sass/partials/global/_functions.scss 
   create arcturus/sass/partials/global/_mixins.scss 
   create arcturus/sass/partials/global/_extendables.scss 
   create arcturus/Gemfile 
   create arcturus/.editorconfig 
   create arcturus/.gitignore 
   create arcturus/stylesheets/print.css 
   create arcturus/stylesheets/style.css 

*********************************************************************
Congratulations! Your compass project has been created.

This gives us our basic directory/file structure. To complete the spinup, we run the bundle install on the new subtheme:

$ cd arcturus
$ bundle install

Which gives the following output:

Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...
Enter your password to install the bundled RubyGems to your system: 
Using addressable (2.3.5) 
Installing chunky_png (1.2.9) 
Using fssm (0.2.10) 
Using sass (3.2.12) 
Using compass (0.12.2) 
Using breakpoint (2.0.7) 
Using bundler (1.3.5) 
Using compass-blend-modes (0.0.2) 
Using color-schemer (0.2.7) 
Using compass-normalize (1.4.3) 
Using css_parser (1.3.5) 
Using sassy-buttons (0.1.4) 
Using sassy-strings (1.0.0) 
Using singularitygs (1.0.8) 
Using toolkit (1.0.0) 
Using compass-aurora (3.0.6) 
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

This grabs all the dependencies that the correct versions, and creates Gemfile.lock. We are now ready to theme.

Our goal is to create our own flavor. So, how?

What's Going On Here?

When compass create ... is executed, the flavor of choice is spun up. The directory structure and the source of the generated files are specified by the flavor manifest. For example, the Polaris Manifest, specifies the directory strucutre and where to look for the file templates. The template files, are farily straight forward.

To create our own flavor, we just need to implement a manifest and associated template files.

Proposed Workflow

Utilizing this toolset for an OS base theme means that we are no longer maintaining a base theme, but rather the maintained unit is a "concept" in the form of a compass extension. Assume for a moment that we have our own fork/branch of ACE, and consider the following workflow.

1. Project X is begun, Turnip is spun up with the only contrib theme in the makefile being Aurora.
2. From within project/themes/custom, we compass create $project -r aurora --using aurora/arcturus.
3. As Project X progresses, commits happen against the project theme. During code review (or whenever) commits are identified as "this should be in Arcturus".
4. Backport the flagged commits into the Arcturus compass extension, and update the gem.
5. Later, before Project Y is spun up with the arcturus flavor, we update our local copy of the gem, then spin up the project with the updated arcturus flavor. It now contains backported optimizations from Project X.

So, each time a project is spun up, the output of compass create ... gives us the latest state of our base theme concept. Under this type of workflow, our PHP theme stack is only two layers thick, and we can more easily pick and choose what goes upstream back into the compass extension. Further, we could feasibly maintain a few different flavors for our use, since the architecture of ACE allows us to mix and match components. To support this, we'll need to figure out how we are distributing the gem for internal use, and how it will be updated. Do we want to host the gem on RubyGems.org?

Actionable Items

If we agree that this is the type of workflow we want to implement, then we have two actionable items towards implementing a flavor:

1. Fork ACE, and create the arcturus flavor
2. Figure out how we want to distribute the gem.

Once we have the flavor the proposed workflow should be easy to implement.