Redesign implementation plan

[furilo]

Here we outline a proposal of how to deal with the implementation of the redesign.

As usual, we kindly ask for your feedback for improving it.

Some context:

• the visual appearance changes significantly. Some functionality changes, but in general they are iterations to simplify things
• we have agreed with Product to try to freeze the development of new features during the implementation to ease with the maintainance. But we asume there will some PRs (mainly bug fixes) that will have to be merged. The objective is that these freeze period is as short as possible. A calendar will be proposed once we agree on the plan
• we propose to start using Hotwired (which implies using Stimulus) for some parts of the new design, with the idea to keep migrating or developing new features using it after the redesign (that is, we won't be able to migrate all now, but we can use it for some new things, and it's there for future things)

Dates

• the objective is to have Decidim Barcelona ready at most in February 2023. To be conservative this means we should have a release ready at most in early December 2022.
• the objective is a release with the redesign of the front-end. Admin redesign will be done later.

Possible plan

Code organization

• we'll create a feature/redesign branch that will go in parallel to develop. Non-redesign PRs will go against develop, and develop will be merged continuosly (automatically?) to feature/redesign
• we'll create a layout called new_layout, that uses new assets.
• we'll start by implementing this layout (header, footer etc) and page by page/module by module. ie. we'll implement the design for proposals, and specify that this module uses the new layout
• you'll browse a complete site, some pages with new layout, others with the old
• when we are done, we'll rename new_layout to layout; deleting old layout and assets

HTML, CSS & JS

• we'll start using Tailwind, stop using Foundation
• we'll start by respecting most of the HTML
• we'll remove/substitute Foundation CSS classes in the HTML for the Tailwind counterparts
• we'll respect the existing named CSS classes (ie. card), we'll change the CSS to use Tailwind
• regarding Javascript, we'll keep jQuery; there are lot of JS relying on class names so to avoid problems with class names, and to prepare for an Stimulus future, we would adapt JS to use data attributes
• we'll start using Sitmulus/Hotwire for new features; existing features relying on jQuery/Ajax can be migrated later.

Out of the redesign scope

Some things we deliberately keep of our the redesign scope, so things don't get out of hand, given that the quantity of work means lots of uncertainty. If there is time available, we may tackle some of it.

• Rails version change
• Webpacker: we consider that while Webpacker will probably go away, it doesn't matter if its done before or after the redesign implementation.
• Complete jQuery substitution: I don't think there will be time for everything

Migration of a highly modified site

What would the migration of a highly modified site (ie. futureu.europa.eu/) could look like?

ToDo: Prepare guide ;)

Let us know what you think.

[ahukkanen]

You pointed out preserving some of the existing class names, which is great 👍, but I just wanted to re-emphasize my main concern: I really (really, and really) hope we won't see any HTML full of the Tailbloat classes.

Good: column layouts, sidebar elements, "prototyping" utilities with caution (= not for everything)
Bad: theming (colors, font-weights, font-styles), hover states, focus states, etc.

[alecslupu]

Considering I have Involved in the initial development of futureu.europa.eu/, i could not say how the migration guide will be, but some of our struggles while developing the application were:

• Living on the edge is a challenge
• Too many blocks (like cells) that we had to override to add our code, or our customization
• The cell system does not support integration with Deface (the tool used to heavily customize the classes and fields)
• There were a lot of items that we did not need from the participatory process meta section, so maybe that would be nice to have configurable from admin (like content blocks that are being displayed on the homepage)
• There were a lot of CSS customization we needed to do, and we have ended up overriding big chunks of existing css

IMHO, for a project like futureu.europa.eu/, a full migration like new Cell design, a full migration may be a pain if is not done properly.

[alecslupu]

Regarding the use of Hotwire, would be a good approach to implement it directly to develop branch as we could remove all the uncacheable information (like follow, number of comments, author data), which is a pain to deal with.

Also, IMHO we should know whta is the JS strategy that we are going to use, as there are some files that are using javascript_pack_tag or appropriate to load additional js. It could be avoided if we are going to use more js events.

[ahukkanen]

Few ideas that I've had for the redesign implementation plan and workflow how to handle the core merge. I may add to this list if I get new ideas to my head but just to start with a few.

These are just ideas that I haven't fully thought out but @andreslucena asked me to share these here. Feel free to apply what you see beneficial and ignore what you don't see beneficial.

1. Build the "working" prototype first

Build the prototype separately in a separate GitHub repository. Similarly to what we have the design app right now in the main repository but separate that to a separate repository.

In this repository, build the necessary Rails configurations, HTML markup and CSS for the different UI components. Overall, test how everything works together and also use this as a way to communicate to the community how things are going to look like, what the code looks like, etc. The idea is to have all the debates e.g. about code organization and such before we start integrating it to Decidim.

The prototype should not have any actual functionality, just lay out how we are going to use the different UI components in Decidim. Very similar to the current design app.

2. Feature freeze for integrating the new UI

Once the prototype is completed and everyone agrees with that, freeze the other Decidim PRs for 2-3 weeks (how long do you think the integration takes?) and start the integration work. This can happen in a single PR or multiple PRs, as you see best. If it happens in multiple PRs, we have to accept that some parts of Decidim UI will be broken during this process.

Agree this beforehand with the maintainers, so that we know what to expect and when. We can also plan accordingly (e.g. how to handle Rails upgrades, etc.) so that we can try to clear as many standing issues before the feature freeze begins.

During this freeze time, just focus on integrating the new UI. Other PRs are going to wait for this process to complete, so this should also not take forever.

Accept also that some JS may break during this process due to changes in the markup. Fix that later (and mark any tests as incomplete that may break because of this). Keep track in a GitHub issue which tests were marked as incomplete (to be fixed).

3. End feature freeze, fix issues with the integration

As separate PR(s), handle the remaining issues with the integration e.g. with broken JS. At this point, we can already continue merging other PRs and continue the fixing process meanwhile.

4. Clear migration guidance for implementors

I suggest picking 10-20 most used UI components/styles from Decidim and writing a clear guidance on how it used to be and how it is going to be in the future. I haven't put any proper thought to what these documented elements would be but some ideas could be:

• Card element
• Button element
• Badge/label element
• Building a form
• Accordion element
• How to show/hide element for different breakpoints
• How to show element only for screen reader
• How to build grids (e.g. 50% split, 1/3 split, main + sidebar, etc.) + how to modify it for different breakpoints
• How to customize the colors of the elements (outside of the ones we can control from the admin panel)
• How to customize the border radius of all card elements globally
• How to customize the border radius of all button elements globally
• How to customize the shadow of all button elements globally

The documentation could look like this:

Element: Card

Before:

<a class="card card--process" role="region" aria-label="Process: Support Forum" href="#">
  <img class="card__image" alt="Support Forum" src="https://placekitten.com/360/160">

  <div class="card__content">
    <div class="card__header">
       <div class="card__title">Support Forum</div>
    </div>
    <div class="card__text">
      <div class="card__text--paragraph">
        <p>This is a space for dialogue and exchange of knowledge among the members of the Community.</p>
      </div>
    </div>
  </div>

  <div class="card__footer card__footer--spaces">
    <div class="card__support">
      <span class="card__button button button--sc small">
        <span class="show-for-sr">Take part in process Support Forum</span>
        Take part in process Support Forum
      </span>
    </div>
  </div>
</a>

After:

TBD

Element: Button

Before:

<a class="button large primary" href="#">Check the new Prototype</a>

After:

TBD

Style: Border radius

Before:

// Place this at your app/packs/stylesheets/decidim/_decidim-settings.scss

// Buttons
$button-radius: 5px;

// Cards
$card-border-radius: 10px;

// Dropdown
$dropdown-radius: 5px;

// Forms
$select-radius: 5px;
$input-radius: 5px;
$form-button-radius: 5px;

// ... etc ...

After:

TBD

[furilo]

Maybe I'm missing something, but if even if you have "finished" with the framework swap, you have a branch that is not finished until all new design has been applied (which the sum of css, html, and rails code). And until you are not finished you can't merge it nor release it (and that means you will have a parallel develop branch), so what's the difference with our proposal?

[ahukkanen]

so what's the difference with our proposal?

That developers of other PRs could already start utilizing the new framework as early as possible.

This way e.g. if there will be UI PRs such as #8681, #8950 (or the related PRs), they could be already implemented on top of the new framework.

[furilo]

But where you would be merging the "new framework" branch? That would be an incomplete and therefore non-releaseable branch. If could be merged to develop, but then develop won't be releseable until the design (css, html, rails) is finished. So in practical terms, you are left in a similar situation, right?

[ahukkanen]

In develop and just live with the fact that it cannot be released until the redesign is completed. And prepare/plan accordingly, i.e. get as many standing PRs merged before that happens and do a release before the "freeze" phase starts.

[furilo]

OK, so linking this to my initial proposal, in the end what you are proposing is that we skip the part of creating a new parallel redesign branch, and that we just work against develop. We are definitely fine with that, as that save us from the sync between develop and redesign.

Are you ok with creating the new_layout/new assets that would coexist with current assets, so we can have some modules/pages using the new layout/assets, and the non-migrated ones the current one? new_layout would become the standard layout when we are done, moment in which develop would become releaseable again.

[alecslupu]

I have read all the ideas, and I am thinking that we can work with something like.

1. Introduce 1 config option for all the engines, that would conditionally allow you to load various design options. I am thinking something like Decidim::Meetings.legacy_design = true
2. Based on that variable we could write at any Engine Base Controller ( ex Decidim::Meetings::ApplicationController) a new helper method that would allow us to specify if the rendered page needs or does not need to load the new layout.
3. Pass that variable to cell context to determine what is the layout needed to be loaded
4. Patch the Webpacker and all assets to be renamed and prefixed with legacy_...
5. Implement a decidim_render method with the only purpose to determine whether is a new or old design.
6. Start implementing the new functionality for each one of the engines.
7. Alternaltivelly, we could create a new Decidim gem named decidim-legacy, where we can migrate all the functionality that we cannot remove yet (for instance Decidim::AuthorCell), which could become Decidim::Legacy::AuthorCell
8. when the migration work is finished, we could remove all the extra functionality.

[paarals]

Good morning!

Today we had a meeting between the maintainers team and the redesign team. Here are the agreements we've reached that are for everyone:

Objective: To discuss strategy of redesign implementation: continuous merging of redesign PRs to develop or merging to feature/redesign

Conclusions

1. Redesign team ask maintainers to do the reviews as frequent as possible so they don't receive feedback late. Objective is to do at least weekly reviews.
2. If a release is near, redesign PRs will go against feature/redesign branch.
3. When a release is done, feature/redesign will be merged to develop.
4. If a release is not near, redesign PRs will go against develop maintainers review and accept PRs no matter which the target is.
5. For now, until version 0.27 is released, pull requests will be moved from development to features/resdesign.
6. Version 0.28 is expected to have most of the new design features already.

Thanks @andreslucena, @furilo for sharing your notes, anything just let me know :-)

[andreslucena]

Just a small change:

• Version 0.28 is expected to have most of the new design features already.

• Version 0.28 is expected to be the last version with the old design. Version 0.29 should have the new design.

[andreslucena]

There's a new update regarding this, please see #9512