Ideas for Improving Giter8 Templates? (Proposed at ScalaDaysBerlin2018)

Scala Platform
1

At the closing panel (precisely at 28:08 in the video) in ScalaDays Berlin 2018, @kelley and @heathermiller mentioned the idea of improving the giter8 templates.

From the video, two improvement goals were mentioned:

  1. make them easier to find and more organized
  2. notify and update the outdated ones

Currently, there is a wiki page that has a collection of templates: https://github.com/foundweekends/giter8/wiki/giter8-templates

I am trying to get a sense of what is missing and what would be helpful to improve.

  • Any suggestions or thoughts on the current wiki?
  • Whatā€™s missing?
  • What would be useful to have?
  • Any ideas on organizing the templates? (For example, making a website or adding a section on scala.docs website resources section to make the templates more ā€œvisibleā€).
  • Any ideas on how to keep the templates up-to-date (without a person having to update everything)?

Any suggestions are welcome!

(Looping in @eed3si9n @smarter @heathermiller @kelley )

3 Likes
2

Maybe templates can be indexed on https://index.scala-lang.org/ alongside with libraries.

4 Likes
3

Thanks Yifan for bringing this topic up.

Around April of 2017 (a bit after sbt new integrated with Giter8) I reorganized the Wiki page from a flat list to the current style. Until then, the template list was a mix bag of new and outdated since Giter8 has been around since 2010.

Official or third-party (done)

At the very top level, the list is split into two major categories:

  1. Templates from official sources (and are up to date)
  2. Third-party and/or old templates

Itā€™s kind of obvious in the hindsight, but Giter8 templates that are maintained by the official maintainers (for example Akka, Play, Scala Native, Unfiltered) have a pretty good chance of doing the right thing, and kept up to date.

Group by the main library (done)

Within the top two categories, Iā€™ve introduced a grouping such as Akka, Play, Scala.js, and Base templates. This too helps to narrow down the list into what the users may be looking for.

Filter out older templates (done)

Template requires constant upkeep, so if there has not been commits for some time, the template is likely no longer useful. When I did the cleanup in 2017, I used 2014 as the cutoff date, so 3 years. If there hasnā€™t been a commit since 2014, the template is displayed at the bottom with the year included in the description.

So whatever we do in the new list, I think we should keep these things in mind, and not revert back to the old flat list of everything.

Ideas: Sort by GitHub Stars

Nothing is perfect, but GitHub star is a good signal of quality/popularity. There are GitHub issue Improper search results, Improve search relevance, ā€œrelevantā€ results arenā€™t where this has been suggested to Scaladex, but thus far it has not been the default.

So why is that relevant here? Letā€™s click on the first ā€œtopicā€ on the front page of Scaladex, which says akka (91).

akka_91
akka_91.png1988Ɨ1788 484 KB

I have no idea how the search index is scored, but ā€œakka/akkaā€ the project that contains the word ā€œakkaā€ in both organization name and the repo name doesnā€™t show up until page 3. Compare and contrast with sorting by GitHub stars, which Scaladex already implements but not by default.

akka_91_stars
akka_91_stars.png1950Ɨ1796 436 KB

Similarly for Giter8 templates, I think it makes sense to sort by GitHub stars within the category. Iā€™ve also used GitHub stars as a metrics while migrating sbt plugins it worked really well.

Ideas: Embrace occasional manual curation

This applies for any search results, but especially for Giter8 templates, I think we should be ok with occasional manual curation as ā€œfeaturedā€. As long as thereā€™s a transparency around it (for example, small icon indicating ā€œfeaturedā€, ā€œpromotedā€, or ā€œeditorā€™s picksā€), that can correct some biases around GitHub stars, which can pick up not-so-relevant result or favor older projects.

For example, in case of ā€œakkaā€ topic, akka/akka, akka/akka-http, and akka/alpakka should just be hard-coded as the top 3 results for now.

Ideas: Encourage engagement with GitHub repos

Another metrics that might be useful is the number of GitHub issues (flatMap :+1:, if possible). If Saladex can surface the number of open issues, that could also be a good signal to filter out outdated or unmaintained templates.

Combining this with the idea of using GitHub star as the default sorting, we should encourage users to hit stars from the Scaladex UI, and also link to GitHub issues to report problems.

Promo: Get Started with Lightbend Technologies

In addition to integrating Giter8 into sbt new, Lightbend Tooling team also made a web UI called Project Starter on our developer portal. See Project Type: Play for example. This runs Giter8 on server and creates a zip file containing the generated source, sbt distribution, and Gradle launcher. Using that, you pick a topic you want to work on, and hit download.

4 Likes
4

Thank you Eugene, for writing down the current state and the ideas!

I second this idea. Either default sort by stars or forks seem more accurate than relevant to me. The discussion in the github issue stopped without an actual fix. We should make a decision soon, and I am happy to look into changing the default search to star.

Those are really good ideas to improve scaladex. Looping in @smarter @julienrf @tpolecat
It also sounds like we will be having giter8 templates alongside with the libraries on Scaladex?

Thanks for pointing out the Lightbend ProjectStarter! This is a super cool tool! This tool runs Giter8 and creates a zip file template project whenever a user downloads one, which ensures the template to be up-to-date. If Lightbend already has this tool, should we collaborate with Lightbend and add more libraries/ Project Types instead of creating another place to organize the templates?
The Project Starter needs some publicity. Maybe it will be helpful to add it on scala.lang website resources section?

5

Thanks for looping me in. I donā€™t have much to add, other than :+1: to using stars, for lack of a better metric. I think the larger problem with g8 templates is that they become outdated very quickly ā€¦ I canā€™t even keep my personal empty Scala project template up to date!

2 Likes
6

FYI, @wsargent automated submitting PRs to update versions: GitHub - playframework/templatecontrol: Template Control for Play templates and other examples

4 Likes
7

Hereā€™s an example checkin:

It runs through all of the Play examples, then Travis CI will ping the slack channel when builds pass. When they do, you just click on the PR link and then click merge / delete.

Itā€™s been a lifesaver on multiple occasions, because it parallelizes builds across Travis. The only downside is that occasionally a PR will get overlooked.

8

Following up on this, you may want to use https://github.com/fthomas/scala-steward and https://mergify.io/ to manage upgrades on test pass.