Migration to landscape2

[tegioz]

Hi! 👋

We've been working on a new version of the landscape generating software, landscape2. Landscape2 relies on the same landscape.yml file as the main data source, so nothing changes regarding adding or updating entries in the landscape.

The CNCF landscape has already been successfully migrated to this new version, and we'd like to start migrating more landscapes 🙂

We are already building the ASWF landscape using landscape2, you can check it out at https://aswf.landscape2.io/. It'd be great if you could give it a try when you have a chance and, whenever you are ready, we can proceed with the migration.

The process is very simple and would involve the following steps:

• [ ] Adding/updating some DNS entries [1]
• [ ] Stop background automated processes that write to this repository (CNCF bot)
• [ ] Unlink this repository from Netlify
• [ ] Update README and clean up some files no longer needed in this repository
• [ ] Setup the landscape2-validate-action to validate the landscape.yml file on PRs (optional)

We can take care of the last 4 points, you'd only need to update the DNS entries.

Landscape2 supports embedding a view with items in a category/subcategory in another website, but it works slightly different than landscape1. If parts of this landscape are embedded using this mechanism on other websites, we'd appreciate if you could let them know about how it works now.

Please ping me if you have any question 😉

[1] We’d need to know the hostnames you'd like to use to prepare our end to listen on them before switching the DNS (i.e. landscape.aswf.io). Once we are ready we'll provide you with the destination for the DNS entries so that you can update them.

[jmertic]

Hey - sure let's flip the switch. Should I do the DNS switch before you make your changes?

[tegioz]

Awesome! What hostnames would you like to use? We need to prepare our end to listen on them first :)

[jmertic]

I'd keep the same as today - landscape.aswf.io and l.aswf.io - would that be ok?

On Thu, Jan 25, 2024 at 8:55 AM Sergio Castaño Arteaga < @.***> wrote:

Awesome! What hostnames would you like to use? We need to prepare our end to listen on them first :)

— Reply to this email directly, view it on GitHub https://github.com/AcademySoftwareFoundation/aswf-landscape/issues/782#issuecomment-1910610065, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACIOIJ2MLZGHTM3L4HMGWTYQKFBXAVCNFSM6AAAAABCJCILQGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMJQGYYTAMBWGU . You are receiving this because you were assigned.Message ID: @.*** com>

[tegioz]

Sure 👍

Could you please create the following CNAME entries? We need them to prove that we are allowed to setup a certificate for those subdomains.

_bb002d7316febc484cebe964c9bebf5a.landscape.aswf.io. -> _26cff91aa15257daccd238586863b2c3.mhbtsbpdnt.acm-validations.aws.
_2554178cb8ac7be21d1a8b0d467ba007.l.aswf.io. -> _50d340e0f29bdb49c177628b07886fc2.mhbtsbpdnt.acm-validations.aws.

Once they are ready I'll update the list of hostnames and will share with you the new destination of the existing subdomains.

Thanks!

[jmertic]

Sure! I put in an IT request for that now. Will let you know once it's done.

On Thu, Jan 25, 2024 at 12:48 PM Sergio Castaño Arteaga < @.***> wrote:

Sure 👍

Could you please create the following CNAME entries? We need them to prove that we are allowed to setup a certificate for those subdomains.

_bb002d7316febc484cebe964c9bebf5a.landscape.aswf.io. -> _26cff91aa15257daccd238586863b2c3.mhbtsbpdnt.acm-validations.aws. _2554178cb8ac7be21d1a8b0d467ba007.l.aswf.io. -> _50d340e0f29bdb49c177628b07886fc2.mhbtsbpdnt.acm-validations.aws.

Once they are ready I'll update the list of hostnames and will share with you the new destination of the existing subdomains.

Thanks!

— Reply to this email directly, view it on GitHub https://github.com/AcademySoftwareFoundation/aswf-landscape/issues/782#issuecomment-1910702716, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACIOIMEDL5JZ6F5U53H4EDYQKLH7AVCNFSM6AAAAABCJCILQGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMJQG4YDENZRGY . You are receiving this because you were assigned.Message ID: @.*** com>

[jmertic]

DNS entries are complete - let me know next steps. Thanks!

[tegioz]

Awesome! Our end is now ready to serve the landscape on landscape.aswf.io.

You can update the DNS record whenever you are ready 🙂

CNAME landscape.aswf.io -> d6o8hzzlhxo5z.cloudfront.net

I understand l.aswf.io is an HTTP redirection to landscape.aswf.io, so that should be OK. We have prepared our end for both hostnames, so if you want to replace the redirection at some point that's fine too.

[jmertic]

Thanks for this!

One QQ on something I noticed; are the pre-renders we had in the old landscape available here? For example...

https://landscape.aswf.io/pages/members

I tried this URL but got nothing...

https://aswf.landscape2.io/pages/members

[tegioz]

No worries!

We have something similar, please take a look at https://github.com/cncf/landscape2?tab=readme-ov-file#embeddable-views (https://aswf.landscape2.io/embed-setup) 🙂

[jmertic]

Nice! What is the best way to migrate the previous embeds over? I'd like to keep the view consistent from before if possible.

[tegioz]

You have a few options to customize the embed view, hopefully that will help you make them look similar 🙂

Regarding the migration: one way would be to update the embeds before migrating the landscape, by using the aswf.landscape2.io hostname that's still on. Then you can switch the DNS records and once it's done you could update the embeds urls to use landscape.aswf.io. This way there would be no down time.

[jmertic]

Hi @tegioz - appreciate this. It doesn't seem to cover the logo only views we used before - see https://landscape.aswf.io/pages/members

It would be great if we could interject in CSS like before; that would allow us to customize the embedding to ensure it is seamless. Could perhaps that be added?

[tegioz]

I think it can be already setup to look very similar on the new one, except for the logos and font size. Please take a look at the example below (prepared using the embed-setup view I shared before):

https://aswf.landscape2.io/embed/embed.html?key=aswf-member-company&headers=true&style=clean&size=md&bg-color=%23ffffff&fg-color=%23000000

[tegioz]

And the logos and font size is something we could make configurable 🙂

[tegioz]

Please note that the url I shared is the embed view configurator. You can adjust a bit the customization options available and once you're ready you can copy the embed code generated (available at the bottom). In this case, I selected the clean style, selected the corresponding members category, all subcategories and adjusted the background and foreground colors. And the result is almost identical to the members example you shared (except for the sizes mentioned).

[jmertic]

That is much closer - thanks! But being able to pass in CSS like before ( see https://github.com/cncf/landscapeapp/blob/5d942291539d4cf03c0aa0fab1457561d3a66416/README.md#adding-css-styles-for-an-embedded-landscape ) would be most ideal to get the full look and feel aligned. Could that be accommodated?

[tegioz]

BTW the logos size is already configurable 😅 This one should look even closer https://aswf.landscape2.io/embed/embed.html?key=aswf-member-company&headers=true&style=clean&size=xl&bg-color=%23ffffff&fg-color=%23000000 (feel free to play with the configurator to find the best match).

Regarding passing custom CSS, we don't have plans for that at the moment but we'll consider it 🙂

[jmertic]

Thanks - I think custom CSS is a huge blocker for us. We will need to pause on further migration until that can be addressed.

[tegioz]

Sure, no problem 👍

I'd like to understand better what's the huge blocker at the moment for the case you shared.

The previous landscape provides this embed view:

https://landscape.aswf.io/pages/members

And the new one provides this one (the logos size can be adjusted if needed):

https://aswf.landscape2.io/embed/embed.html?key=aswf-member-company&headers=true&style=clean&size=xl&bg-color=%23ffffff&fg-color=%23565656

I may be missing something but the main difference I see is just the header font (size/family). And we'd be happy to make that configurable (or maybe some other parts that I'm missing at the moment). We've switched other embedded views on the cncf.io and k8s.io sites and it's been fine so far.

Before going down the CSS route, we'd like to understand first a bit better what parts will need customization and how can we make it easier for users to customize them. Asking users to understand what styles they need to tweak -and how- looks more complex, and probably will require individual support on many cases. So our goal was to provide a self-service configurator that allows them to create customized embedded views using a simple UI. We'll consider the CSS definitely, but if there is a way to do it that provides a better experience, we'd like to give it a try as well.

In addition to this, we've also added recently an API that allows consuming the landscape data easily to build custom views, just in case it helps 🙂

[jmertic]

Hey @tegioz, I appreciate your thoughts and suggestions on this.

Some examples of where you'd need more that just the configurator are:

https://www.aswf.io/members/ - see how closely the theming aligns with the overall theme https://landscape.openmainframeproject.org/pages/members?style=body%7Bbackground-color:white;%7D.borderless-mode%20.mosaic%20.logo%7Bheight:100px;%7D.sh_wrapper%20span%7Bfont-size:40px!important;text-decoration:underline;color:black;%7D%23embedded-footer%7Bdisplay:none;%7D.borderless-mode%20.mosaic-wrap%20%7B%20padding:%2010px%2020px%7Ddiv%5Bdata-wrapper-id%3Dopen-mainframe-project-member-company-platinum%5D%20.items-cont%3Aafter%7Bcontent%3A%22%20%2B1%22%3B%7Ddiv%5Bdata-wrapper-id%3Dlf-energy-member-general%5D%20.items-cont%3Aafter%7Bcontent%3A%22%20%2B3%22%3B%7Ddiv%5Bdata-wrapper-id%3Dlf-energy-member-associate%5D%20.items-cont%3Aafter%7Bcontent%3A%22%20%2B3%22%3B%7D - this is a view I used for creating a drop in ready list of members for our overview decks. I'd need to do a bunch of tweaks to make the view otherwise as we want.

The API route could be an alternative, but this does add an extra layer for us to build to replicate the functionality. I could see advantages to that for something like a website ( embeds, while more convenient, are a bit of a cludge and slows the site load ) and maybe even being a layer for caching when the landscape is down, but other views and times we can't make those adjustments then require a more complex solution.

Hopefully this context helps!

[tegioz]

I think you'll be able to handle both cases with the configurator. We just need to allow some control over the fonts, alignment and logos spacing. All generic stuff that will be useful to other integrators, so it's not a problem to extend the configurator a bit (up to a reasonable point).

We need to take care of a few things but we'll get back to you as soon as it's ready. The result should be good enough so that it's barely distinguishable 🙂

Going back to the CSS route and looking at the example url you shared:

https://landscape.openmainframeproject.org/pages/members?style=body%7Bbackground-color:white;%7D.borderless-mode%20.mosaic%20.logo%7Bheight:100px;%7D.sh_wrapper%20span%7Bfont-size:40px!important;text-decoration:underline;color:black;%7D%23embedded-footer%7Bdisplay:none;%7D.borderless-mode%20.mosaic-wrap%20%7B%20padding:%2010px%2020px%7Ddiv%5Bdata-wrapper-id%3Dopen-mainframe-project-member-company-platinum%5D%20.items-cont%3Aafter%7Bcontent%3A%22%20%2B1%22%3B%7Ddiv%5Bdata-wrapper-id%3Dlf-energy-member-general%5D%20.items-cont%3Aafter%7Bcontent%3A%22%20%2B3%22%3B%7Ddiv%5Bdata-wrapper-id%3Dlf-energy-member-associate%5D%20.items-cont%3Aafter%7Bcontent%3A%22%20%2B3%22%3B%7D

When something like this is encouraged/documented, the structure of the code becomes part of the contract, like if it was an API. Those styles you defined may be relying on a given html tag, element id, class, etc. Any change to any of those entities could break part or all the work you did. IMHO this seems fragile and would lead to not being able to evolve the embed page as we could be breaking any of -potentially- many integrations. The internal representation of that page is an implementation detail that could change at any time (new framework used, some redesign, etc), so it should not be relied upon.

Please note that allowing injecting styles is easier than what we are doing. But IMHO it's not the right approach, but a potentially problematic and restrictive one. That's why we are a bit hesitant about it.

Let's work together to get you a bit closer to what you want, but always keeping in mind that the final result may not be a pixel-perfect representation of what you would like to see 😇

[jmertic]

Hi @tegioz - I'm completely fine with removing the CSS gymnastics if these can be accomplished via the tool. Let's see how close you can get and we can go from there - thanks for all the work here!

[tegioz]

Please take a look 🙂

https://aswf.landscape2.io/embed/embed.html?key=aswf-member-company&headers=true&category-header=false&category-in-subcategory=true&item-name=false&title-uppercase=true&title-alignment=center&title-font-family=sans-serif&title-font-size=24&style=clean&size=xl&items-alignment=center&items-spacing=30&bg-color=%23ffffff&fg-color=%23b09a5e

You can fine tune it from the embed configurator if needed.

[jmertic]

View looks great - thanks!

But when clicking on a logo, it opens up a whole new page. Could it instead work like before where it would open in the current page?

[tegioz]

Awesome!

When you click a logo, it takes you to the full landscape. We did this intentionally to drive traffic into it and let more users know about it. But we'd like to add that back as an option at some point.

Ready to do the switch? 🙂

[jmertic]

Got it - that is one issue I know much of our community was a big fan of; any sense of timing of when that would be added back in?

[tegioz]

TBH I don't know at the moment. We still have a few things pending on the landscape, plus quite a few more on the other projects we maintain. And we're working on a new project as well! 😅

I was hoping that the benefits of having the new landscape would outweigh the missing bits, but I'll leave that up to you. Looking forward to seeing the ASWF landscape in v2! 🙂

[jmertic]

Got it - yeah, I would at least like to wait till next week as there is some legwork for me to do on the embeds, and we have an event on Thursday, so I don't want to do a cutover until after the event. I think the feature would be nice to have, but probably not a blocker at this point. I appreciate all your help!

[tegioz]

Awesome, no worries!

Please ping me when the DNS switch is done so that we can help with the other points in this issue.