Document process of switching from generic theme to GC theme

[mgifford]

It isn't clear in the documentation how to switch from the generic design, such as you get here: https://drupalwxt.github.io/

And the default GC theme, such as you get here: https://open.canada.ca/en

I remember there being a simple toggle or something somewhere in the D7 theme, but am not sure where that is in D8. Either way it needs to be documented.

[zachomedia]

I think you might mean this section which we documented in the starterkit?

https://github.com/drupalwxt/wxt_bootstrap/tree/8.x-1.x/starterkits/wxt

This script is something we also use for subtheme that might do most of the configuration for you:

/**
 * Implements hook_install().
 */
function canada_core_install() {
  $theme_list = [
    'claro',
    'canada_experiments',
  ];

  // Install themes.
  \Drupal::service('theme_installer')->install($theme_list);

  // Get theme manager
  $system_theme = \Drupal::configFactory()->getEditable('system.theme');

  // Set default and admin themes.
  $system_theme
    ->set('default', 'canada_experiments')
    ->set('admin', 'claro')
    ->save();

  // GCWeb
  $config = \Drupal::configFactory()->getEditable('wxt_library.settings');
  $config->set('wxt.theme', 'theme-gcweb');
  $config->save();
}

And for the library itself which is linked above can just add this to config/install/wxt_library.settings.yml for your custom module

url:
  visibility: 0
  pages:
    - 'admin*'
    - 'imagebrowser*'
    - 'img_assist*'
    - 'imce*'
    - 'node/add/*'
    - 'node/*/edit'
    - 'print/*'
    - 'printpdf/*'
    - system/ajax
    - 'system/ajax/*'
    - 'admin*'
    - 'imagebrowser*'
    - 'img_assist*'
    - 'imce*'
    - 'node/add/*'
    - 'node/*/edit'
    - 'print/*'
    - 'printpdf/*'
    - system/ajax
    - 'system/ajax/*'
theme:
  visibility: 1
  themes:
    canada_experiments: canada_experiments
    wxt_bootstrap: wxt_bootstrap
minimized:
  options: 1
files:
  types:
    css: css
    js: js
wxt:
  theme: theme-gcweb

[sylus]

Added this to the theme itself so is also documented.

https://github.com/drupalwxt/wxt_bootstrap/commit/095a501bdf70187b5110b875ed48d0205b8ac6ef

Thanks for taking the time!

[mgifford]

@zachomedia this is helpful. There's no real documentation in the project page that tells you that there is a Readme.md for the WxT starterkit that we should be looking for that would help. A link from the starter page would help.

I'd prefer if this stayed open so that as someone who isn't part of the core team I could be satisfied that the documentation and process is clearly described. This should get us a lot closer.

If there is central documentation somewhere, that too should be clearly linked to from the project page.

I'm on GCMessage, so happy to chat there. Not sure how active folks are here in either drupal or wet-boew channels there but happy to talk about these ideas in other places.

@sylus if you're just going to say that, then put it in the project page up front & centre https://github.com/drupalwxt/wxt_bootstrap

You could go a step further and say that no support is provided for this theme and limited support is provided for the distribution. It's really up to you and how eager you are to see adoption of your work.

Frankly I don't think that most departments are going to know or care about what you've added here. I'm not sure that the majority of Drupal users are all that familiar with Lightning, let along your average government web person.

I can see advantages to using the distribution, but it's an impediment for many people. It's also just not frankly how most of the Drupal community works. I understand this is different and you've added a lot of government special sauce to the distro. It's also a lot of bulk that many folks haven't bought into.

I don't find your response helpful or structured in a way that will help build community around Drupal in government. I assume this is what you & I both want, so I am confused as your response doesn't seem to indicate that.

[zachomedia]

@mgifford We understand that some documentation may be lacking, and while we are constantly adding and improving documentation, we have focused on areas raised by the community to ensure that they can succeed in their projects. For every issue that you have opened so far, we have addressed and documented as requested.

Should you feel that the documentation that has been provided is incomplete or can be improved, we happily accept contributions from the community. This issue was closed because the original issue was address. This would fall in line with standard development practices in any project. Should you have continued concerns about documentation that has not yet been addressed, we are happy to have new issues created for those on Drupal.org.

Regarding wxt_bootstrap / wxt_library and their support both with and independent from the wxt distribution: the distribution uses the 2 modules directly. Ensuring that the modules are up to date and functional is a core component in the WxT release process (https://github.com/drupalwxt/wxt/wiki/Release-process). We offer them separately for those who aren't able/interested in using the distribution. We offer limited support for those setups (ie. we will try to help when we can) because we do need to prioritize the time for work that will have the largest impact on users.

Of the users we've been in contact with, they are using the distribution instead of rolling their own Drupal install using wxt_bootstrap. This is why our support focus is currently on the distribution. To ensure this is well documented, we even added a notice about this on the wxt_bootstrap project page (@sylus's comment above).

Just a quick note about some of the additional benefits of the distribution:

• We support Docker and Kubernetes single click installs with it
• We have numerous departments using it and stats extensively extending it with their sub profile
• We have a proven track record over 2 years of maintaining it and updating it as evidenced by our changelog
• Have provides contrib support for any of the modules we add under the profile

The distribution is also fairly lightweight, contains many optional features. Lightning provides a a base, some pre-configuration, authoring lifecycle (enterprise authoring) as well as many upgrade paths. We also have a relationship with Acquia, who provide us support when needed and builds components that goes into core. They've also provided us the base for the composer workflow and upgrade paths. Lightning is use in many large organizations and has a 2000 site install, and Acquia recommends using it as a base especially for governments.

We understand that not everyone may be interested or able to use those features, however, and again is why these modules are separate from the distribution.

[sylus]

Thanks @zachomedia and sorry I closed the issue it was because I thought we addressed the specific issue as the title of the issue was worded to something specific and I pointed to the commit. Additionally I thought we had a discussion earlier where you asked us where we prefer issues and we both agreed to Drupal.org. Sorry about that.

We are definitely trying our best to accomodate as best we can. Really sorry if we fall short in some areas. :( Both me and Zach do this all essentially in our open source time now since we are in a different field now at StatsCan. The WCMS team at stats only takes the reins once Drupal 7 is sunsetted in the next 4-6 months and then should have a team of between 5-8 supporting it.

In general from the departments I have heard form they were pretty happy with our work and we already have 3 depts in production one for over 2 years so we also have to maintain upgrade paths and support for them. I know of 3-5 others that have it in the pipeline so also want to make sure their path is as smooth as possible.

Lightning itself has been great as the people who maintain it have worked closely with us in the past and many huge sites run with it as a base. It itself whole goal is to be a base framework from which to build upon. They even solve all of the complicated upgrade paths for us such as when panelizer was deprecated by layout builder, and even the composer workflow in general which is now the recommended practice for building drupal sites though we early on to that. Additionally they have slowly moved all their logic into their component modules so at some point we will also lose the profile dependency which is planned in the long term.

As for the notes themselves we do always update the README.md for all of our main projects but sometimes we do forget to upgrade the documentaiton pages on Drupal themselves as they are a bit more work and not in markdown. I have added that to the release process so they aren't missed and we try to sync up with the README.md files.

[mgifford]

Thanks @zachomedia & @sylus for this. Misunderstandings happen, especially in issue queues.

Remember that there are over a million installs of Drupal so having almost 2000 sites using Lightnight isn't at all significant. Not sure how that even stacks up even in Acquia users. My point wasn't to dismiss Lightning though. I'm sure there are lots of places where it adds a great deal of value.

I'll be satisfied in this issue when there is a clear path from DrupalWxT to the sub-themes. How does an outsider go from say here: https://github.com/drupalwxt/wxt

to here: https://drupalwxt.github.io/

to here: https://github.com/drupalwxt/wxt_bootstrap/tree/8.x-1.x/starterkits/wxt

If documentation is going to be put in Readme.md files, or other locations then it also needs to be linked up to what you define as your central documentation page.

I don't see anything about the starterkits in wxt. Maybe it isn't needed in the distribution. But if that's the case then say so. Document what is functionally different about the two. And no, I'm not interested in hearing about either Lightning or Docker. I know they are great, but that's just not the reality that most government departments are allowed to play in.

[joel-osc]

Hey @mgifford - maybe this is something we can add to the next steering committee agenda as an opportunity for people outside of Stats Canada to contribute. @zachomedia, @sylus do a great job of everything, but I am sure they would be happy to get some help! Especially, if you can document from an outsiders perspective the process for using the distro in a variety of applications. Cheers.

[mgifford]

Just wanted to say that @zachomedia & @sylus can't do a great job of everything. They do an amazing job on a hell of a lot! That said, very few developers like documentation or do it well.

WxT & DrupalWxT are big projects that really could use a lot more resources dedicated to them. It is unreasonable to assume that this small team can take it all on, and do it all right.

Yes, people in the community should step up and take on responsibility. But the core team behind DrupalWxT has a lot of influence over how this happens. Just being in the habit of saying something like:

• did this resolve your concern?
• are there ways this could be improved?
• if this didn't answer your concerns, bring it up on GCMessage in the Drupal channel. Someone from the community will help you there.
• we've done the best we can here, but would really appreciate a PR if you want to take it further.
• does your team have time to contribute to the documentation (testing, community engagement, etc.)?

That gives a way different signal to people trying to use your code than a rather canned response "Thanks for taking the time!" and closing the issue.

[zachomedia]

@mgifford Lightning is something that is being used by and built for governments, and provides much of what is needed to create a Drupal-based content management system that meets the needs of the Government of Canada. It's also used as the basis of government Drupal platforms around the world (https://www.acquia.com/blog/building-drupal-8-sites-acquia-lightning-cuts-costs-100000, https://www.drupal.org/docs/8/distributions/degov/about-degov, https://github.com/govcms/govcms8). And as the primary contacts of the WxT system, we have a good feel for what our users have requested and need. Everyone that we've worked with on their projects have been using the distribution. We even have a couple going down the Docker route, based on what WxT provides. We are in frequent contact with many users of the distribution.

The great thing about WxT (and lightning) is that you can pick and chose what components you want to use. We don't force you down a certain path. And if you don't want the full distribution, or lightning, then you can use the wxt_bootstrap / wxt_library modules seperately in a standard Drupal installation.

We would be curious to know what departments you have been in contact with and what their current Drupal adoption situation is and their choice between the distribution and just the theme? We'd be happy to work with them more and understand their use cases, and understand if they are currently hitting any roadblocks as we haven't heard of any.

The documentation for doing that exists today in the README.md of either the distribution or the wxt_bootstrap module itself, and the project pages have been updated. We've even recently added more clarity on those in response to the issue that you opened. The README.md is a common place in software projects to have this documentation. We're also focusing our documentation efforts on where a majority of our users are currently focused, and we're always willing to accept documentation contributions from the community where there is a need for improvement.

[zachomedia]

If you would like to continue the discussion about documentation, please open an issue on Drupal.org.