KB: Technical requirements discussion
I'm going to try to summarize all the various technical requirements I've been hearing from developers related to the knowledge base product, and what I perceive to be the majority or team expert's opinion on them. Then, I'll call out specifically unresolved questions that seem like important decisions to at least agree on a beginning stance for before we get started.
Let's use this discussion to note disagreements or major points of contention. Let's NOT attempt to resolve them here, but to establish an agenda to meet and discuss as a team. To be clear, I reiterate: This is my perception of the state of decisions, not decisions I've made for you. I'm quite sure I will get several of these wrong, which is the point of surfacing them now.
Please discuss as a group whenever possible rather than 1:1. Keep minutes if I'm not present and summarize them here or in the R&D: KB chat. Don't try to resolve them all at once; prioritize by what is the biggest blocker.
Lastly, wherever possible, let's please remember to choose the option that removes blockers, increases our overall velocity, and/or reduces our maintenance costs (generally in that order of priority). I'd like to see our discussions couched in those terms rather than personal preferences.
Technical Decisions
- Server-side rendering is required for some parts of KB. It will not be done with React.
- Vanilla's style.css, default master template, and customer styling (both custom theme files and the Customize Theme addon stylesheet) will not be applied to KB. All existing customers wishing to use KB will require a few hours of services to match the color scheme of their forum and main site.
- A new master template will be used.
- We will make accommodations for customers to specify a custom header and footer (without altering the master template) and customize their color scheme. No other customization or styling options will be available in the first version of the KB. (i.e. "Reduce the margin on this widget by 5px" will not be acceptable feedback from a customer.)
- KB will not support IE11 beyond basic legibility and navigability.
- KB will use dynamic CSS variables by implementing a server-side build process.
- KB will prioritize accessibility by adhering to the criteria for a WCAG 2.0 AA rating.
- KB will use a templating system that is not Smarty.
- KB will drop support for Vanilla alt views: Adding .json, .txt, or .rss to pages should not deliver alternate views.
- All new code will be namespaced and adhere to our new, stricter MVC guidelines.
- Conduct all data access and manipulation via API v2 endpoints.
- No cross-applications calls into Dashboard or Vanilla applications will be allowed.
- Adequate unit test coverage is required for all new code.
- KB will be structured as an addon. It will live in its own repo a la Analytics and use its own version number.
Major Questions
- What templating engine?
- New base model?
- New base controller?
- Eschew global functions entirely?
- How long can we sidestep server-side CSS builds from blocking us?
What other questions are critical to discuss?
Comments
-
I agree with this list. The only detail I will add is there will be some shared SCSS partials between dashboard and the KM, so we can use the same variables and not duplicate common component styles.
0 -
> KB will use dynamic CSS variables by implementing a server-side build process.
I have a question about this topic. From what I know at the moment we can not generate styles per client, but only per cluster. Is this limit still in place? Or we are about to build per Client?
0 -
We currently manually build custom client themes with their own styles. Clients with shared core themes do not.
We currently fork themes all the time for clients, which makes it extremely difficult to make updates. The dream is that in the future, a client's custom theme would be a config file and some CSS variables and that's it. @AlexanderKim we can meet to discuss this if you like.
1 -
What templating engine?
It seems we have settled on twig for any server rendered, SEO required views, and React for the everything else.
New base model?
This is a yes. @Ryan is currently working on it.
New base controller?
Initially not, but it seems we are now. Essentially every facility `Gdn_Controller` provides for pages currently is being done in a different way in knowledge management.
- Rendering views is being handled differently (react + twig)
- Data is being fetched/sent to the client differently (API + ReduxTrait)
- Breadcrumbs are being handled differently.
- Pagination is being handled differently.
- Assets such as styles and javascript are being handled differently.
- Theme integration is being handled differently (by not being handled at all right now)
Other things we can re-implement or use `Vanilla\Web\Controller`.
- Permission checking.
- going to the event manager (which we shouldn't be doing initially)
- redirects.
Eschew global functions entirely?
Yes please.
How long can we sidestep server-side CSS builds from blocking us?
@slafleche was discussing this with me a little bit today.
CSS variables seem to be too restrictive for a generated sheet of variables. As a result they do not provide much benefit.
We may end up going with a CSS in JS solution for certain parts of the styles that need to be highly configurable. This would allow us to utilize 3rd party, pre-made, supported tooling instead of rolling our own. Many of these still allow us to use readable class names if we desire and have performance profiles similar to precompiled stylesheets.
1
