Technical Discovery for Snippet View refactoring to Vue
Original technical discovery
Original discovery by @pslaughter
Scope
Snippet edit page:
From the frontend, the edit page can remain the same - a new edit simply adds a new version on the backend. Thanks backend!
Snippet show page:
This is the only page we'll consider at the moment since it's the only one requiring upcoming changes.
New functionality (versioned snippets) components
At it's simplest implementation, versioned snippets will require the following UI components (whether implemented in HAML or Vue):
- Tabs
- Revision list
For page load performance, we should avoid loading all the data at once, which requires that some scripting is necessary. Migrating to Vue can make implementing these new features more efficient and reliable, while staying in HAML + Vanilla JS can make things difficult to test and maintain.
Existing functionality components
So what does migrating to Vue look like? Here's a list of components which compose the current snippets UI:
- Page Header (can be left in HAML)
- Title
- Description
- Embed actions
- File header
- File content
- Comment box
Thankfully there's some preexisting components we can reuse here, making these changes mostly trivial. Some non-trivial components include the file header and content. There's an opportunity of reusing preexisting components here, but it's not perfect.
Another non-trivial piece is loading the extra data that's needed (e.g. snippet previewed content, snippet links, extra meta information). Most of this is already available in the API, but some new fields will probably be needed.
Reusability opportunity
It looks like we can easily reuse the existing CSS.
The following components contain mostly reusable code, but some will require some refactoring to make reusable for our case:
- Markdown comment Vue component
- Reaction component
- Use of clipboard in Vue
- File component:
Concerns
There's some crossover with the new file component and MR diffs. We should make sure we do this right and find an abstraction that serves both. I label this as a concern, because this will require some attention.
Rest vs. GraphQL
Since we will probably need some more data properties exposed in the API, it's worth evaluating whether now is a good time to migrate to GraphQL. This is especially relevant as the schema for the API will grow in complexity due to the upcoming features.
Cons:
- Extra work involved with unfamiliar area.
Opportunities:
- It's easier to create requests that progressively load the page (i.e. load file heads, and then content). This is because the only work needed is to define the shared schema (not each individual request/response).
Pros:
- Easier full stack collaboration.
Proposal
Should we refactor snippets to GraphQL now?
I'd like BE to weigh in on GraphQL vs. Rest. From the FE, the immediate costs could outweigh the benefits, but it's possible the long term BE benefits are worth it.
Should we refactor to Vue now?
Yes. This will greatly help implement the changes being proposed in the versions feature and future features.
Proposal
I suggest we do a Vue refactoring (no new features) behind a feature flag in one release. We might need some new data exposed in the API (e.g. rendered snippet content), so if we're planning on also migrating to GraphQL, we should probably do this in one swing to minimize the amount of temporary code.