canon
canon copied to clipboard
rackerlabs
Migration Proposal
As we've discussed the path from Canon to Canon Bootstrap, concerns over the value-effort trade-off have been raised by a number of different teams. Specifically, the following issues have been raised:
- A full migration is going to be risky and expensive.
- Not every team will have the resources to devote to a migration.
- Most of the teams who are already using Canon were early adopters. By changing libraries, we are penalizing early adopters by forcing them to perform another migration.
- Canon is the result of ~1800 commits and ~30,000 lines of code and documentation by a dozen contributors. As the Paper Street team has found, there is a tremendous amount of work to replicate all of Canon's features inside Canon Bootstrap. By just switching to a new library, we're essentially throwing away this work and creating a new pool of work for a project that already lacks full-time developers.
So far, we've assumed that a fork in the road is necessary to move to a Bootstrap-based design framework. I don't believe that is the case and propose the following strategy for introducing Bootstrap into Canon.
- Release Canon v2.0 essentially as it exists today (v1.8.1) but with one major difference: it packages a skinned version of Twitter Bootstrap to make it look at home alongside Canon. Most of this work has already been done in the Canon Bootstrap repository.
- Introduce a series of minor version releases that re-implement Canon's
rs-*classes in terms of Bootstrap. For example,.rs-btnbecomes an alias for.btnin Bootstrap. This prevents a complete re-write of frontend code to use the new class names. Additionally, it means teams who are usingrs-*classes continue to receive improvements without rewriting their control panel. The key with this step is very small, focused releases to minimize the risk of defects. - As patterns have been successfully ported to Bootstrap, introduce deprecations for the Canon's
rs-*classes. They will continue to work and (in most case) receive updates, but new code should use Bootstrap's version of classes instead. - Introduce Canon v3, fully built on Twitter Bootstrap. All deprecated
rs-*will be removed. This is likely 12-18 months in the future.
I think this approach works well because it minimizes rework, allows a more gradual migration path, and continues to deliver improvements to teams already using Canon for many months to come. What do you think?
Huge fan of this strategy and the idea of evolving instead of forking. Thanks so much for putting this together.
Few detail questions:
- After step 1, could canon-bootstrap consumers just start using canon?
- Will step 2 cause visual style changes as we gradually move elements to Bootstrap implementations?
So this is similar to what Eric mentioned. Use both until you can migrate to just bootstrap. In this example we'd be aliasing canon classes to the bootstrap code through v2 releases. The goal will be to transition together during this time vs ripping off the bandage early on. Eventually v3 will be pure bootstrap.
It makes a lot of sense. I only wish we did this from the get go. I think this is most beneficial to canon users vs canon-bootstrap. It would be pretty awesome to have 1 codebase again.
I noticed that sometimes bootstrap has way more markup than canon. So step 2 could be tricky. Easy for buttons, more complicated for layout/navigation where markup is different.
@racker80 did you have an alternative migration path for users? Your example proved both libs could co exist. Like I said, this feels along those lines but could change things.
@eddywashere From my perspective, the big differences are:
- Maintaining support for existing applications in 2.x releases. One of the big issues with moving to Canon Bootstrap was breaking the automatic upgrade path for applications that might not choose to migrate to Bootstrap class names. This resolves that by continuing to support and delivering enhancements during the migration period.
- We don't have to re-implement the considerable amount of work that has already been done on Canon's documentation. Also, there will be some RS-specific patterns that don't exist in Bootstrap. We can just iterate on the existing implementation.
- This proposes an intentionally incremental migration path. Rather than perform a big bang bunch of feature parity work, this proposes per-pattern releases to minimize risk of introducing defects. This may have been possible with @racker80's proposal, but I don't think we ever got around to discussing the details of what migration looked like. However, most of the issues that have been raised have been around migration specifics, so I think they need to be an explicit part of any proposal.
@ajcoppa
After step 1, could canon-bootstrap consumers just start using canon?
Absolutely, but we need to make sure they aren't creating work for themselves by using classes that will be deprecated in the future. However, there will likely be RS-specific patterns that don't have a Bootstrap counterpart. Consumers get immediate access to the implementations that already exist in Canon.
Will step 2 cause visual style changes as we gradually move elements to Bootstrap implementations?
In most cases, I don't think that step two will necessitate any visual design changes. However, there were some planned visual design changes that we might choose to make along the way. I think this is where small, focused releases are important to the strategy. We should re-implement on Bootstrap and then update the styles (or vice versa) if we think that it will minimize the chance of introducing defects.
However, as @eddywashere mentioned, there will be situations in which re-implementation on top of Bootstrap will not be possible because of substantial visual and/or markup differences. Funnily enough, this was a big reason why we didn't go with Bootstrap in the first place -- there were tons of irreconcilable differences between Bootstrap and the RED patterns we were implementing. Unfortunately, re-implementing on top of Bootstrap won't be possible in these cases. I would suggest getting them as close as possible and immediately deprecating the Canon version.
:+1:
I like this approach, it creates a way forward that meets current needs and shows a clear path for canon going forward.
Besides the visual changes, there are some Canon functional components, defined in https://eafdbc63c97ce6bec9ef-b0a668e5876bef6fe25684caf71db405.ssl.cf1.rackcdn.com/v1-latest/canon.js , that may need to be re-factored for use with Canon-Bootstrap.
@fidoogle For a first pass, they should still work fine because existing Canon class names aren't going away. However, I don't think anyone is using pure JS anymore and we should just deprecate them before Canon v3 rather than maintaining components that aren't seeing use.
I like this approach
My only worries are that there could be some weird layout issues when putting the two libraries together (more from my MyRack experience) and some tech debt created to create workarounds to get the libraries to work together and then ripping that out in v3.
On the other hand having one codebase, leveraging all the previous canon work/documentation, and the aliasing approach to adoption are big wins and probably worth it.
@davismartin Yeah, I've seen issues with the two libraries together, too. My hope is that merging them into one will allow us to fix these issues rather than creating workarounds in one place or the other.
@bradgignac While there might not be anyone using this anymore, the idea of encapsulating functionality within a js file (such as bootstrap.js) really simplifies the code needed for producing functional components as in this example (see code for the cog menus) http://embed.plnkr.co/DZve4R/preview . So I imagine there is going to be a canon-bootstrap.js file, if not already?
@fidoogle I definitely agree there is value in shared JS, but I'm not convinced that the existing jQuery-versions will be able to be wrapped effectively. Instead, I hope we'll continue to see framework-specific components emerge in the vein of rackerlabs/rs-popover, rackerlabs/rs-section, and rackerlabs/canon-react.
@bradgignac agree, good thoughts like yours is what these conversations are meant to bring out
+1
This makes a lot of sense and makes migration a lot more feasible, especially for MyRack. I echo @davismartin sentiments about some early issues that are likely to occur by combining the two, but the short-term issues are definitely overshadowed by the long-term gains. This is a much clearer path for migration than simply rewriting everything.
Here's a list of the teams that have expressed support for this strategy:
- [x] AWS
- [x] MyCloud
- [x] MyRack
- [x] Mailgun
- [x] Cloud Backup
- [x] Cloud CDN
- [x] Cloud Office
- [ ] Cloud Sites
- [x] ObjectRocket
I pinged @ddubbindustries from Cloud Office. Anyone have a good contact on the ObjectRocket team?
@bradgignac To wrap a third party library and use it as an injectable library, we use the .value method in Angular, as in this example http://embed.plnkr.co/K8T1UJ/preview We can thus effectively replace the library with any other version.
:+1: to this entire idea. Our team has been using canon-bootstrap for a while now, and we are already removing the use of rs-* prefixes throughout our code base, so this idea sounds pretty solid.
Sticking with boostrap as the underlying framework adds IMMENSE value to canon as a whole.
Cloud Office approves. We are not deeply invested in either version at the moment. We just peppered in the original Canon for a few features of our existing control panel likely never to upgrade it. And going with whatever is bleeding edge for our full stack redesign.
Not sure why I'm included I this discussion...
On Jul 30, 2015, at 8:11 AM, Dave Williams [email protected] wrote:
Cloud Office approves. We are not deeply invested in either version at the moment. We just peppered in the original Canon for a few features of our existing control panel likely never to upgrade it. And going with whatever is bleeding edge for our full stack redesign.
— Reply to this email directly or view it on GitHub.
After talking through with @bradgignac @davismartin @mcortez1497 and @fidoogle - we've got this into a single plan.
Please check out the google doc to get an overview of canon V2, V2.X and V3 - i.e. what, the order, the goals, and the why behind the approach: https://docs.google.com/a/stevesanderson.com/document/d/1bPlGK5Q_3TaZt5A0ey6HQvkJOoOFecwnZHq_wA0hLX0/edit?usp=sharing
The specific cards are in trello (links from the google doc).
I'm not part of this team - please remove me from all future communications.
Thanks.
On Aug 12, 2015, at 4:04 PM, Steve Sanderson [email protected] wrote:
After talking through with @bradgignac @davismartin @mcortez1497 and @fidoogle - we've got this into a single plan.
Please check out the google doc to get an overview of canon V2, V2.X and V3 - i.e. what, the order, the goals, and the why behind the approach: https://docs.google.com/a/stevesanderson.com/document/d/1bPlGK5Q_3TaZt5A0ey6HQvkJOoOFecwnZHq_wA0hLX0/edit?usp=sharing
The specific cards are in trello (links from the google doc).
— Reply to this email directly or view it on GitHub.
Oops, whoever added "ddubb" must have thought it was me, sorry, ambiguity is a way of life for someone with as generic a name as "Dave Williams".
Anyway, the Cloud Office Control Panel has very little dependence on any version of canon at the moment and our team is flexible to adjust to whatever path makes the most sense.
ddubb, Github does not allow us to unsubscribe someone from a thread once mentioned. Very annoying. Our bad. Since I still see you're subscribed, you'll need to manually click unsubscribe.
