Customizability of v1.0

[dfuchss]

Hi @alshedivat,
today I recognized the plans of v1.0 to modularize al-folio (or parts of it). Probably, I did not understand everything, but from what I've seen in the v1.0-dev branch, I cannot find any _layout folder anymore => I guess those have been moved to the modules (?).

From my point of view this raises the question of future customizability of al-folio?

I'm quite happy with using al-folio for my website, but I created some personal tweaks in the liquids (nothing I would say needs to be in the main al-folio repository; because I also disable simply some parts that I don't need/want).

As an example; a very simple tweak that changes some urls if you click on an element in my repositories page:

In the past, it was quite easy to do this: I simply edit the liquid file and can easily sync that with the upstream repository via GIT; sometimes you have to deal with merge conflicts, but they are not that often and most of the time, git handles the merge.

With the upcoming modularization, it is not clear to me whether I will need to fork every module where I want to make an update in a liquid file (in order to easily keep track of changes that occur in future updates of those modules).
If thats the case customizations would come with the price of having to sync multiple, building custom gems, deployments etc.

Do I miss anything or what will be a future way of customizing a liquid + tracking changes with upstream, without forking those module repositories?

Best regards,
@dfuchss

[dfuchss]

Maybe as a side note / question:

I already had the case, where I wanted to update/fix a liquid in a module (see #3535).
If the affected file would have been in the repository a fix would have been easy (and a PR as well).
As far as I can see for #3535 (and any future bugfix in an al-folio module repository) fixing an issue would also include releasing a new version of al-folio in order to trigger new docker images etc. instead of simply merging upstream and re-using the current docker image.

Is that right or is there a more easy way?
I try to figure out, what the future maintenance effort for my personal and projects websites will be 😅 (And I fear that I have to maintain x forks for just some websites because of some minor tweaks 😅 )

[dfuchss]

To those who might have similar questions regarding the upcoming v1.0 release:

I think I found a solution that will work for me: If I modify a module, I'll add it's code as subtree; not optimal, but in doing so, I can keep track of upstream changes while directly modifying the code of the module.

For #3535 I already tested this: dfuchss/fuchss.org@ab6160d

And that seems to work :)

[alshedivat]

I tested this concern against a real heavily customized fork before finalizing the v1 docs. The rehearsal target was dfuchss/fuchss.org, since that is the active customized site and includes local _layouts, _includes, _sass, _plugins, _modules, workflow, config, CV, publication, repository-page, and Matrix .well-known changes.

The short answer is: heavily customized sites should not need to fork every v1 gem. The intended migration path is to keep the starter fork small and customize through config, content/data, local layout/include/Sass overrides, and Bundler pins for plugin versions or Git refs. A plugin fork is only needed when the site wants to change reusable plugin-owned behavior for more than one site or carry a long-lived patch that cannot be expressed as a local override.

The rehearsal found one important practical rule: old local copies of plugin-owned runtime files can block migration. In dfuchss/fuchss.org, the first v1 audit reported 4 blocking issues, all from stale local _includes/head.liquid and _includes/scripts.liquid copies that still loaded the old Bootstrap/jQuery/MDB runtime. After removing those stale runtime overrides and old helper plugins/assets that are now owned by v1 gems, the audit dropped to 0 blocking issues and the migrated site built successfully.

I added the detailed notes and docs updates on v1.0-dev:

• Migration rehearsal log: https://github.com/alshedivat/al-folio/blob/v1.0-dev/MIGRATION_REHEARSAL_FUCHSS_ORG.md
• FAQ answer for local overrides versus plugin forks: https://github.com/alshedivat/al-folio/blob/v1.0-dev/FAQ.md
• Heavily customized pre-v1 migration steps and Bundler pin examples: https://github.com/alshedivat/al-folio/blob/v1.0-dev/INSTALL.md
• v1 ownership table for moved paths and features: https://github.com/alshedivat/al-folio/blob/v1.0-dev/CUSTOMIZE.md

The Docker release behavior is also clarified there: plugin patch releases do not require a new starter release unless the starter wiring, lockfile, or image changes.

[dfuchss]

For an example see: dfuchss/fuchss.org#2

[jenna-jordan]

@dfuchss your repo was extremely helpful for me in figuring out how to customize and repair the various bugs in the theme. I ended up using and building off of many of your customizations (especially for the CV page). Have you considered releasing your customizations as their own plugin, to make it easier for others to also adopt these enhancements & fixes?

[dfuchss]

Hi @jenna-jordan, I'm glad to hear the repository was helpful! 😊

I've been thinking about releasing it as a plugin, but first I need to verify whether that's actually feasible. Some of my changes modify parts of al-folio-core, so it may not be possible to package everything cleanly as a standalone plugin.
Realistically, I probably won't have time to look into this before the end of the year.
More generally, I find that splitting the project across multiple repositories can make it difficult to implement or fix certain parts of al-folio. For example, I'm currently waiting on an open PR in the dependent repository jekyll-socials.