CONTRIBUTING.md

Contributing

How do I add something new to Potassium?

Template

In the lib/potassium/templates folder, you will find the template.

Now, to add some behavior, thanks to the DSL we have a kind of standard flow of what happens when a new project is created. To understand this better, please read the template. The structure looks like this:

1. Clean the Gemfile and add the base gems that rails needs to work.
2. Run all the ask methods from the recipes.
3. Execute all the create methods from the recipes, that are ruby classes stored on the recipes folder. Here you can specify what gems are needed and register callbacks based on this process, usually to execute things after the gem installation happened or after some other recipe finished his work.
4. Install the gems, filling the Gemfile before with all the gathered gems.
5. Finally, create the database.

The main step is the 3rd, when we call the create methods from the recipes. A recipe can do anything (because is a ruby script) but their responsibility should be to gather gems and register callbacks for the process.

Recipe

The recipes are classes defined in the Recipes module that inherit from Rails::AppBuilder and by convention can implement some of the following methods ask, create and install. They take this form.

class Recipes::MyRecipe < Rails::AppBuilder
  def ask
    #...
  end

  def create
    #...
  end

  def install
    #...
  end
end

The recipes should be created in the lib/potassium/recipes folder.

Methods

For example, if we want to create an optional recipe to add a gem called banana_split that needs to run a generator, we can do the following.

| ask

This method is used if you need to ask something to the user before doing something.

1. Use the answer method to ask something using the methods defined in Inquirer, that we use by default. Use the DSL to store some information.

   def ask
     use_banana_split = answer(:banana_split) do
       Ask.confirm("Do you want to use Banana Split?")
     end
     set(:use_banana_split, true) if use_banana_split
   end

2. Then, register the question you created in the template:

   run_action(:asking) do
     # ...
     ask :myRecipe
   end

| create

We'll call this method to add specific functionality to the rails project.

1. In the create method register a gem using gather_gem and create a callback to be called after the gem_install action succeeds to run the generator. gem_install is one of the main actions that should be easily visible with a sneak peek in the template.

   def create
     if get(:use_banana_split)
       gather_gem('banana_split', '~> 1.2')
   
       after(:gem_install) do
         generate('banana_split:install')
       end
     end
   end

2. Then, register the recipe creation in the template:

   run_action(:recipe_loading) do
     # ...
     create :banana_split
   end

| install

The install method will be called when you use the install command from potassium. For example, if you run potassium install devise this will use the recipe template to load and execute the install method for the devise recipe.

You can define the main functionallity of a recipe in a private method and call it from the create and install methods.

def install
  if gem_exists?(/banana_split/)
    info "Banana Split is already installed"
  else
    install_banana
  end
end

private

def install_banana
  #...
end

The DSL

To see further documentation of what we added to the rails template's DSL, check the DSL documentation.

Remember that the DSL we are documenting is an extension over the Rails Application Template DSL, that itself is a DSL based on Thor.