FAST v3 documentation and setup

[janechu]

Description

Currently we have some working ideas for FAST v3 that need some additional documentation and workflow refinement.

Requirements

• Create an issue with general updates for FAST v3 for community feedback
• Remove the web-components folder and flatten the packages to be packages/fast-element/ etc. in main
• Snap archive branches for fast-router and fast-ssr and remove them
• Snap a branch when above issue is created releases/fast-element-v3
• Create a new issue template for FAST v3 branch updates which mandates and specifies where markdown documantation should live for public APIs - This presuposes that we are switching to another documentation system (away from Docusaurus) that can take markdown files and turn them into static HTML.
  • Create a documentation folder to hold new documents in releases/fast-element-v3
• Create any additional tags or milestones for FAST v3 issues

Intent of Changes

We intend to keep the main branch and releases/fast-element-v3 in sync, we must make large scale changes first in main in order to cut down on rebase complications. These changes should not affect the published packages @microsoft/fast-element until the launch of FAST Element v3. This is a re-alignment towards our mandate that FAST is for filling gaps in the browser. We are also committed to documentation first as a development principle, we want to ensure that there are no gaps when publishing our v3 version that must be backfilled and that the community and developers using our packages have full context of the changes as they go in.

Next Steps

• Post issue with current general plan for v3

[chrisdholt]

I think this is great, I do want to make sure that we track and provide guidance on a few things. I think it would be beneficial even if early to provide that context in a singular tracking issue or milestone. My expectation is that we aren't necessarily "around the corner", but can we give insight into how early we are, etc? Additionally, I think it'll help to get an issue out ASAP on the removal of Router, I know it's been in beta but I also know folks have reached for it. In terms of SSR, a removal issue along with some context on what will replace it would be valuable.

I'm all for flattening things back out now that we've reduced packages, I think my unrelated feedback here would be to ensure we don't end up with a monolithic package or one that's hard to use/consume.

Last thought that I have is migration - we should keep track of what all is changing and what might potentially be able to be automated via codemods. Can we have an "ease of upgrade" path for some of these to avoid painful changes wherever possible? How do we track those best.

Aside from that, LGTM.

[KingOfTac]

For moving away from Docusaurus to something else Starlight is a very good option that meets the above criteria.

https://starlight.astro.build/

[janechu]

I think this is great, I do want to make sure that we track and provide guidance on a few things. I think it would be beneficial even if early to provide that context in a singular tracking issue or milestone. My expectation is that we aren't necessarily "around the corner", but can we give insight into how early we are, etc? Additionally, I think it'll help to get an issue out ASAP on the removal of Router, I know it's been in beta but I also know folks have reached for it. In terms of SSR, a removal issue along with some context on what will replace it would be valuable.

This is in preparation of the work beginning, one of the key issues we ran into when going from v1 to v2 was that we did some file moving in the middle, which meant we lost a lot of git commit history (or at least the ease of use of looking at historical file changes). If we begin the process by moving folders and files into locations that make more sense early on we circumvent the problem, then we can begin posting about the work, this will also make rebasing easier. We can re-address the Router situation later, let me take that off our line items (it was a little ambitious, we can receive feedback for it in the meantime). Certainly for SSR and our goals with FAST HTML I can broadcast with our strategy going forward.

I'm all for flattening things back out now that we've reduced packages, I think my unrelated feedback here would be to ensure we don't end up with a monolithic package or one that's hard to use/consume.

Yes, for fast-element specifically since it is parallel to the naming sense of HTMLElement we think that is fairly straightforward when flattened no need for the extra web-components folder. fast-element remains the custom element solution. For fast-html we intend to fold that into fast-element once it is stable as part of our new feature offerings for v3. As for fast-ssr, since that is a NodeJS solution, and we are shifting focus to allow for more broad backend implementations, if that is removed we only have fast-router, which we can determine what direction to move with it on v3 launch, but at the very least it is somewhat obvious as to what platform gap it is filling.

Last thought that I have is migration - we should keep track of what all is changing and what might potentially be able to be automated via codemods. Can we have an "ease of upgrade" path for some of these to avoid painful changes wherever possible? How do we track those best.

We will plan for and have a comprehensive migration guide, that along with documentation-first as stated, will be our goal for this next phase.

[janechu]

For moving away from Docusaurus to something else Starlight is a very good option that meets the above criteria.

https://starlight.astro.build/

I'll put it in the list for consideration!