How to migrate Activator template to Giter8 template

By @eed3si9n March 17, 2017

sbt new command is supported in sbt 0.13.13 and above, which integrates with open source Giter8 out of the box. For example, setting up your first Akka project is as easy as:

$ sbt new akka/hello-akka.g8

It is our recommendation to migrate any active Activator templates to a Giter8 template.

The details of template creation can be found in Making your own templates page. Please read it for the detail related to Giter8. The following outlines a typical migration from an Activator template to a Giter8 one.

step 1. move current files to a temporary directory

Suppose you’re porting activator-hello-akka template. First git clone the template to your machine. Then create a temporary directory under /tmp (or somewhere else you like).

$ git clone git@github.com:typesafehub/activator-hello-akka.git
Cloning into 'activator-hello-akka'...
  ....
$ mkdir /tmp/hello-akka

Next move everything into the temp directory.

$ mv activator-hello-akka/* /tmp/hello-akka
$ ls /tmp/hello-akka
COPYING               LICENSE               activator.properties  build.sbt             project/              src/                  tutorial/

step 2. sbt new foundweekends/giter8.g8 –name=activator-abc

Next run sbt new to start a Giter8 template in the same directory. This is so we can maintain the Git history.

$ sbt new foundweekends/giter8.g8 --name=activator-hello-akka
....

Template applied in ./activator-hello-akka

step 3. Place content files under src/main/g8

Next, move back the template content files into src/main/g8 directory.

$ rsync -a /tmp/hello-akka/ ./activator-hello-akka/src/main/g8/

You can manually copy each files over too.

step 4. License the template under CC0

We recommend licensing software templates under CC0 1.0, which waives all copyrights and related rights, similar to the “public domain.” If you followed step 1, CC0 should be mentioned in README.markdown.

For activator-hello-akka, it’s already licensed to CC0, so we just need to move LICENSE and COPYING file to the root directory.

$ cd activator-hello-akka
$ git mv src/main/g8/LICENSE ./
$ git mv src/main/g8/COPYING ./

step 5. Place tutorial on README.md

Migrate any tutorial contents to README.md.

For activator-hello-akka, let’s just move the tutorial/ directory back to root:

$ git mv src/main/g8/tutorial ./

step 6. Port metadata

First move activator.properties back to root:

$ git mv src/main/g8/activator.properties ./

Next copy name and description from the file to src/main/g8/default.properties.

name = hello-akka
description = Akka is a toolkit and runtime for building highly concurrent, ....

step 7. Test the template

To test the template run:

$ sbt
> test
....

If Giter8 plugin is correctly configured, it should create your template on a temporary directory and run test inside it.

> test
[info] Updating {file:/templates/activator-hello-akka/}root...
[info] Resolving org.scala-sbt#sbt-launch;0.13.13 ...
[info] Done updating.
Falling back to file copy for /templates/activator-hello-akka/src/main/g8/src/main/scala/HelloAkkaScala.scala: File: /templates/activator-hello-akka/src/main/g8/src/main/scala/HelloAkkaScala.scala, 12:52: '"
    case Greet           => sender ! Greeting(greeting) // Send the current greeting back to the sender
  }
}

object HelloAkkaScala extends App {

  // Create the 'helloakka' actor system
  val system = ActorSystem("' came as a complete surprise to me
Running activator-hello-akka / scripted
[success] Total time: 107 s, completed Mar 21, 2017 8:41:46 PM

step 9. Escape any use of $ in the source

Giter8 uses $ as for varible substitution. If you have $ in your template content under src/main/g8, then you need to escape it by replacing it with \$.

Alernatively, you can tell it to skip the variable substitution for some files using verbatim property:

name = hello-akka
description = Akka is a toolkit and runtime for building highly concurrent, distributed, and fault tolerant event-driven apps.  This simple application will get you started building Actor based systems in Java and Scala.  This app uses Akka, Java, Scala, JUnit, and ScalaTest.
verbatim = *.scala *.java

step 10. Append “.g8” to the GitHub repository name

For example if your current repository is named akka/activator-hello-akka, rename to akka/hello-akka.g8.

$ git remote set-url origin git@github.com:akka/hello-akka.g8.git

That’s it!

extra credit

You can migrate the tutorial to Paradox document, which is a GitHub friendly documentation tool.