Remove theme submodule from main

[alancleary]

Currently the LIS Jekyll theme is included as a submodule of this repo. This is to make development of the site and theme simultaneously seamless. However, future site content managers and other groups that want to use our site as a template for their own sites should not have direct access to the theme. For this reason, the theme should be installed as a gem from RubyGems.org in the main branch.

Accomplishing this will likely require setting up a dev branch that has the theme as a submodule but that automagically prevents it from being merged into master.

[sammyjava]

FYI it was bugging me, so I removed it as a submodule on my shokin branch -- my understanding is that submodules are created during clone so nothing changed on main, but I'm not 100% sure. _themes/jekyll-theme-legumeinfo does appear as an empty directory if I do a clean clone of the repo without specifying any submodules. Which is a bit odd, I didn't know you could have an empty directory in a repo. In any case, just an FYI that I did this.

[alancleary]

But if the theme isn't a submodule then where is it being loaded from???

[sammyjava]

Just a standalone repo cloned under _themes. You can do that, I've done it in other repos (the mines, keeping common code away from mine-specific code, when they're a bit interleaved). You do have to add _themes to .gitignore, of course, or just _themes/jekyll-theme-legumeinfo if you're planning to write other themes along with the site (which I don't). Perhaps not kosher, but I prefer it. It does work.

[sammyjava]

[shokin@shokin-jekyll jekyll-legumeinfo]$ cat .gitignore 
_site
.sass-cache
.jekyll-cache
.jekyll-metadata
.DS_Store
vendor
_themes
*~

[alancleary]

Just a standalone repo cloned under _themes. You can do that, I've done it in other repos...

OK, that "works", but there's no mechanism for ensuring the correct version of the theme is installed. The submodule approach at least tied the theme to a specific commit. And the RubyGems.org approach mentioned in this issue would've tied the theme to a semantic version. So I don't think we should proceed with removing the submodule from main until there's a mechanism in place for specifying the theme as a versioned dependency.

[sammyjava]

I agree, and I just confirmed that I didn't change anything for a git clone --recurse-submodules https://github.com/legumeinfo/jekyll-legumeinfo.git whew.

[nathanweeks]

The theme submodule was convenient when it was undergoing rapid development, but it has probably outlived its usefulness at this point. We might consider reverting to using jekyll-remote-theme pinned to a specific commit until an updated theme artifact is available via RubyGems.org.

[alancleary]

Thanks for mentioning the jekyll-remote-theme plugin, Nathan. I completely forgot about it! It seems like a very seasonable intermediate solution.

[sammyjava]

Well, and I'm still editing my branch of the theme. I tweaked tools-menu.html and added taxa-menu.html. It seemed to me that those belong in the theme since tools-menu.html was already there and taxa-menu.html is the same kind of thing.

The distinction between theme and site may need a bit more clarity. I'd be happy to put all my changes under the site, but then what stays in the theme? Lots of stuff that is overridden on the legumeinfo site? That seems odd, but, OK, if the theme is meant to be a bare-bones minimum that is overridden/extended on any given site, that's fine. I don't really care where the code sits.

Practically speaking, what I'm working on is the shokin branch of jekyll-legumeinfo and the shokin branch of jekyll-theme-legumeinfo, and some day in February I'll want to merge my branch up to the dev, then main, branch of both site and theme to make the site go live.

If what I'm doing on the theme isn't appropriate theme-wise, I should blow away my theme branch and do all my changes locally on the site as overrides, sticking with the main theme branch as a submodule. Let me know, @alancleary if I should do that. I'm totally happy to, I just have to make it work, which I think should be straightforward (just copy directory and file names, right?)

[sammyjava]

Along the plug-ins line, although this is different, I added this to my Gemfile:

  ## handy way to see if an image exists on the site
  gem 'jekyll_file_exists', :git => 'git://github.com/asperduti/jekyll_file_exists.git'

I use that to see if a plant image exists on the taxa pages. But that's on the site, not the theme.

[sammyjava]

OK, I just blew away the shokin branch of the theme after copying those changes over to the shokin branch of jekyll-legumeinfo. I feel like I'm doing site-specific things there, and the plan is for the theme to be very generic. I can always copy them back to the theme if so desired. So now I'm all set to pull the theme from a gem, having the appropriate overrides in place.

[alancleary]

OK, I just blew away the shokin branch of the theme after copying those changes over to the shokin branch of jekyll-legumeinfo. I feel like I'm doing site-specific things there, and the plan is for the theme to be very generic. I can always copy them back to the theme if so desired. So now I'm all set to pull the theme from a gem, having the appropriate overrides in place.

Sorry for the slow reply on this. I don't have the bandwidth to keep up with all the changes you're making, so what should go in the theme vs the site will have to be done at your discretion, and I mostly agree with what you've said in this thread. Although, I will now clarify the role I've been imagining the theme plays (I am open to input/debate since other people in this thread are much more directly affected by this than me):

I've been thinking of the theme as a modest default site, so not necessarily "a bare-bones minimum that is overridden/extended on any given site", i.e. if another group wants to get a site going but they don't have the resources to override/extend the theme, the theme by itself will provide a production ready site that covers the basics of such a site.

Given this role for the theme, it should be no surprise that LIS is overriding a lot of the theme because, unlike the target demographic of the theme, we have resources for site maintenance and development.

[nathanweeks]

I've been thinking of the theme as a modest default site, so not necessarily "a bare-bones minimum that is overridden/extended on any given site", i.e. if another group wants to get a site going but they don't have the resources to override/extend the theme, the theme by itself will provide a production ready site that covers the basics of such a site.

FWIW, some static site generators make the distinction of referring to such a bare-bones site as a "starter" as opposed to a theme (e.g., Gatsby, or Bridgetown, which bills itself as the successor to Jekyll).

[alancleary]

Thanks, Nathan. I think "starter site" is definitely the way to think of the theme, although I think for conformity with the Jekyll community it should still be called a theme, i.e. jekyll-theme-legumeinfo (we should probably change the legumeinfo bit).

[sammyjava]

I'll report that I've moved the theme to be part of the shokin branch and moved my _includes and _layouts into the theme, as it is now local code. After the datapages-generator experience I decided I've veered far enough from the standalone theme to abandon it, it's not providing any value beyond two stylesheets.

[alancleary]

it's not providing any value beyond two stylesheets.

Perhaps the value has dwindled for LIS, but I think it still retains more than two stylesheets worth for other sites, such as soybase. Specifically, it defines the styling, layout, and core data a biological information system should have.

The LIS project is well funded and stacked with developers. So of course our site is going to go well beyond the facilities of the theme. However, by distilling the essence of the site into the generalized theme we are doing a great service for less fortunate groups. Not only do they get off the ground much faster, we also take on the burden of core development and maintenance; they just have to focus on content.

If the LIS stakeholders don't think maintaining a generalized theme is a worthwhile endeavor, then so be it. However, if the only issue is that it's slowing down our march to release then I think dropping the theme is short sighted.

Also, FYI, the stylesheets currently in the theme are not the precomiled ones provided by UIkit. I compiled the theme myself so I could update the colors for the LIS site. I was planning to automate this compilation in the theme and make the colors customizable via the config file.

[sammyjava]

I think the theme is great as a starter. It's just expired its usefulness for the site that I'm developing. I'm sure glad I had it to start with, though.

[sammyjava]

In other words let's for sure keep the theme alive in its own renamed repo to indicate its general usefulness.

[sammyjava]

This happened, so I'm closing it.