search

SharePoint / sp-dev-docs

SharePoint & Viva Connections Developer Documentation
https://docs.microsoft.com/en-us/sharepoint/dev/
Creative Commons Attribution 4.0 International
1.24k stars 1k forks source link

🙏 ISO clarification on SPFx's dependent library versioning & rollout policy #325

Closed andrewconnell closed 2 years ago

andrewconnell commented 7 years ago

Category

After reviewing the docs in this repo, in the wiki & on dev.office.com as well as watching all the PnP stuff, I haven't been able to get the following answer... maybe I've missed something but asking around, seems to be an outstanding question...

What's the policy for rev'ing dependent library versions? For simplicity, I'll focus on React since SharePoint has a strong bias towards React. If I am going to build web parts that use React & the Office UI Fabric, as a developer I need to understand how versioning is handled within SPFx / SharePoint as a whole.

This is important when you consider the following scenarios:

If there is a policy... then...

I'm not talking about updating my web part from vX to vX+1. I'm talking about something like React / Office UI Fabric. React has monthly drops & is progressing quickly.

andrewconnell commented 7 years ago

EDIT: raised this issue in the PnP JS SIG biweekly call on JAN-5-2017... the answer was that there is currently no policy but it's recognized as something that will be shared by GA.

IMHO: This is a pretty important thing... as many developers will not want to take a blind dependency on something, esp something so core to SPFx as React, with zero visibility into the versioning & upgrade story of that dependency.

shaipetel commented 7 years ago

I'd like to add to the question - other libraries such as Knockout or Angular, that also don't play nice when you have more than one version on the same page. Would be good to get guidelines on how to tackle this for all libraries and not specifically for react

sympmarc commented 7 years ago

This is a set of issues all of us client side folks have been dealing with for years. It definitely gets harder when you are shipping a product with dependencies, for sure, but it is possible to have a good strategy.

One might think that turning to some outside parties who are already doing this well would be a great idea. This isn't an area where a "not invented here" mindset would be very useful.

shaipetel commented 7 years ago

I'm afraid it is not that simple, while in other fields usually there is a customer who knows what is running on his site, and can make everyone comply and play nice together, here we are talking pages that are dynamic-by-design, to the point that the end user is the one who can throw any number of different combinations of web parts and components to the page, in any order he like. I do think this is quite a unique situation in web programming, which most libraries today do not handle very well (with exception of maybe jQuery noConflict option, which even that 99% of developers I know don't bother to use).

On the one hand, having MSFT say: Use vX for library Y might do the trick, but rouge developers might not comply, might load a different build by mistake or perhaps could not comply. On the other hand, letting us load what we want and let us fight the version war ourselves is no solution at all... Some are more skilled than others, but it only takes 1 unskilled developer to bring down a whole page.

The only other option I can thing of is if MSFT will load the most common libraries for us, on a version they decide/control. But I am sure this will make a lot of people unhappy if they are forced into a choice. IMHO - that should have been done a long time ago with jQuery on SharePoint... but that is another story.

andrewconnell commented 7 years ago

@sympmarc: This is a set of issues all of us client side folks have been dealing with for year

Totally agree... but that isn't the same issue, nor is it unique to client-side. The challenge SPFx introduces into this one is the fact you are deploying your customizations (that you control) into their environment (that you don't control) that has dependencies that you can't dictate / control... or at this time, have any visibility / expectation on the upgrade policy.

That's no different than us deploying our custom server-side components into SharePoint 2007 / 2010 / 2013 onprem before, except for one very significant difference: We're going from the dependencies having a 3yr ship cycle to a 1mo ship cycle. In the case of the issue I opened, React has monthly drops.

shaipetel commented 7 years ago

Yeah, the more frequent ship cycles is what makes it a bigger issue. But the main challenge in SharePoint is that even if you do a project for a customer and not a product, you still don't know what is going to be on the page alongside your code tomorrow. That's usually not the case for web developers elsewhere so it isn't a common issue in web development and that's why (I assume) most libraries did not bother addressing this scenario.

Unless MSFT is going to rebuild angular, react, knockout etc. To be isolated- I don't see a simple solution for this issue except loading it as a part of the framework on a specific version for everyone to use.

Falkayn commented 7 years ago

The question goes back to whether/how SPFx isolates different apps? If it can do it with some sort of magic - I had thought iframes where involved - then this may be a moot question. Otherwise, yes, it is a major issue.

shaipetel commented 7 years ago

The whole point was to not reply on iframes since they are too isolated and never render properly. They use isolation in the sense that your code is wrapped in self-calling functions so that solves name conflicts and the need for namespaces. The problem is that almost all libraries rely on global objects and that's the main problem. While some libraries can solve it like jQuery no conflict do. Others rely to heavily on globals and hook up many event listeners and lots of CSS classes it would just be nearly impossible to add isolation to them.

shaipetel commented 7 years ago

*rely, not reply...

Falkayn commented 7 years ago

I thought the custom webpart's JavaScript libraries were going to be loaded in the ifame and the rendering was to be done in the SPFx 'canvas' area - but I haven't been keeping up with the work. Without some sort of 'magic' being involved we end up needing to rely on everyone being well behaved, and that includes the SharePoint devs themselves ;)

waldekmastykarz commented 7 years ago

There are no iframes involved in loading libraries in SPFx, however if you use SPFx to load a library then it's loaded encapsulated. If you for example would have two web parts on the page one using jQuery 2 and the other jQuery 3 then it would all just work and both web parts would be using their correct version - even without using noConflict.

Falkayn commented 7 years ago

Thanks Waldek! How does that relate to @andrewconnell original question then?

waldekmastykarz commented 7 years ago

If I understand it correctly @andrewconnell's question is related not to libraries you load yourself and therefore control but to libraries provided to us by SPFx. Given that these libraries are not bundled together with the web part, but loaded from SPFx, it could be that with the next release of SPFx things don't work/work differently due to a change in one of the libraries.

Theoretically it should be possible to load React in web parts yourself rather than using the version provided with SPFx. So if you want more control about the libraries you're using, you could try doing that.

shaipetel commented 7 years ago

Waldek, your comment for jQuery is only partially correct since the global object will still only be registered once in one of the versions unless you use the no conflict in your code you may affect other components on the page in case they are relying on it and may break them (non SPFx ones as well as SPFx ones in case they even use a library that relies on window.jQuery object).

But yes, for the SPFx project, wrapping it inside a self calling function creates your own scope - I guess that is the "magic" Falkayn might be referring to. that's a good trick but far from issue-free, and the problem with CSS and JavaScript global objects and listeners will present a big challenge... i must say the current CSS solution they offer with dynamic class names doesn't make a lot of sense to me in real life where I would like to apply branding to my components separately than the component package.

waldekmastykarz commented 7 years ago

You're right @shaipetel: if there are elements on the page that depend on the globally set library then there is a risk they will break. One could argue that depending on globally loaded libraries is something that you can safely do when you own the page and know its building blocks, which cannot be said of web part pages where users can change the composition at any time.

shaipetel commented 7 years ago

Well, sadly, lots of libraries do it even if it is not a good practice. Angular does it as well in some parts calling window.angular specifically looking for the global object.

Here is an excellent read about it which captures all aspects of how this magic works and the issues that come with it: http://www.mattburkedev.com/multiple-angular-versions-on-the-same-page/

This is basically if I am not mistaken what you mean by "load your own library", which still might prove not to be a simple task without tinkering with the library's code.

My point is, the only way to really support this is if these libraries plan to support it. And currently AFAIK none of them support it by design, some might support it by chance with some wizardry.

An interesting topic indeed. Good night!

andrewconnell commented 7 years ago

Let's keep this one on topic... this isn't a question about loading libraries... it's about dependencies. The fact MSFT includes React on the page & that you can't have two versions of React on the page makes the dependency question very valid & separate from dynamic module loading.

shaipetel commented 7 years ago

Not just react. I've seen OOB stuff in new experience that use knockout if I am not mistaken.

But I have to disagree on your take to limit just to talking about react since a solution/best practice/recommended approach should be adopted in my honest opinion to all major libraries.

chakkaradeep commented 7 years ago

Let me try to get more clarity on the problem here than trying to explore solutions:

  1. @andrewconnell 's concern is that there are set of libraries used by SharePoint. If my solution is using one such library, how do I manage those in my solution and how do I know what is available?

  2. There is also a greater issue of how do I as a developer manage the dependencies and its versions, especially some libraries that require global variables like jQuery, Angular 1.x etc.,\

I also want to stress that this is a problem even to internal Microsoft development teams as these use cases are common across client-side driven development unless you are building your own bespoke web application.

Regarding (1) - Agree there are very little information around, especially around React support. @patmill and @pgonzal will be the right folks to start this discussion. I am sure we have the info, its probably not documented or articulated in a good way.

Regarding (2) - Unless those dependencies are provided by Microsoft (something like what Wordpress does ), it relies a lot on the developers. This isn't different to challenges developers face today with client-side development. But IT IS DIFFERENT as to that now developers will have to think through on how their solution will be integrated natively into another solution. Pretty exciting and challenging at the same time. Add-ins necessarily don't have this problem as nothing really lives in SharePoint. You can consider an add-in almost a bespoke solution than an integrated native solution. You can also seek some help from browser cache as they usually do help if many web parts for example load the libraries from the same CDN path (a scenario common amongst enterprises than ISVs distributing web parts).

Some of it are easier if we are able to understand and use libraries that are suitable to scenarios. For example, while Angular 1.x is a great successful framework, it's just painful and entirely not of Angular 1.x's interest to build native widgets unless those widgets are inside one singular Angular app. It makes it harder to manage and deploy web parts in such cases. In other words, there is no one library/framework that will do everything and cater for all types of solution scenarios.

At Least for enterprises it can be recommended to validate/choose a set of libraries to depend and build their solutions on top of that.

I feel that answers to some of the points in (2) are a bigger problem that extends beyond SPFx and applies to generic client-side development. But we should see what we can do with (1).

Hope that helps. Thanks for starting this thread. Lets get more ideas and feedback!

andrewconnell commented 7 years ago

Thanks for chiming in @chakkaradeep ... totally agree to this:

I feel that answers to some of the points in # 2 are a bigger problem that extends beyond SPFx and applies to generic client-side development.

This issue had some comments get away from the main point which is # 1 above... my original concern.

I'm looking forward to hearing how you plan to handle this. Since posting this I've had a few reach out privately to me saying they are staying away from React because of the void of clarity on this topic... hopefully something before GA ;)

patmill commented 7 years ago

@andrewconnell - can you confirm that the heart of your question is "Microsoft is providing a version of React as an SPFX library.
What happens if I want to use an updated version of React that MSFT/SPFX hasn't wrapped?
What happens if SPFX starts including React 15.6 when you ask for react, and that has a breaking change (or a bug) that makes it break my webpart that was built using 15.4? What happens if 3 different versions of react (or some other wrapped library or 1st party SPFX library) need to be loaded because there are 3 solutions on the page that require different versions?

andrewconnell commented 7 years ago

@patmill yup... that pretty much nails it... except...

What happens if 3 different versions of react (or some other wrapped library or 1st party SPFX library) need to be loaded because there are 3 solutions on the page that require different versions?

This isn't possible to the best of my knowledge as React doesn't do well with multiple versions on the same page. I'm not 100% clear on this though as I haven't spent much production time with React other than learning samples to tinker a bit. This is just what came up when I went searching if this was an issue with React just as it is with Angular.

octogonz commented 7 years ago

If I understand right, this conversation is about third party packages being wrapped up as "client-side library" components, i.e. Microsoft has bundled them according to our guidelines, registered a manifest, and will take responsibility for releasing updates. The goal of course is to improve perf, by having everyone share a single bundle on the page.

Currently we do this for react and lodash because we need it ourselves. We have said that in the future, we will do this for a number of popular libraries, as a service for developers. Eventually we will probably also open up the "client-side library" component type so that third parties can do the same thing.

What happens if you release a web part that relies on React 0.14.x, and then we upgrade to React 0.15.x? We have two choices:

  1. Prove that it is forwards compatible, and then be on the hook for any accidental regressions.
  2. Create a major breaking version, which will then cause the library to be loaded side-by-side.

Either way, the goal is to ensure that an already shipped web part will not be broken, while allowing new web parts to use the new functionality.

wobba commented 7 years ago

@patmill and this also goes into SPFx GA guidance. Should we as developers go React, as it's already loaded, or should we fear using it as it can be updated at will to match MS web part life cycles.

We need to know pro's and con's when advising customers, which is more important than what we actually use.

andrewconnell commented 7 years ago

@wobba - We need to know pro's and con's when advising customers, which is more important than what we actually use.

Let's first start with a stated policy & then we can see what the pros & cons are from that. :)

octogonz commented 7 years ago

@patmill and this also goes into SPFx GA guidance. Should we as developers go React, as it's already loaded, or should we fear using it as it can be updated at will to match MS web part life cycles.

I don't understand this fear. If you don't want to use Microsoft's bundle, you always have the option to maintain your own bundle of React.

wobba commented 7 years ago

@pgonzal I'm no expert, but @andrewconnell said above that React doesn't play well with multiple versions on the same page, which I interpret as it might not be smart to load my version of it. I'll sit this one out until we have policy and all the answers :)

andrewconnell commented 7 years ago

@pgonzal there's no fear here... just trying to get a clarification. Clearly, it's better to leverage a library that's already on the page instead of adding weight. And to do that, you need to understand what the maint. & support story is around what you're taking a dependency on.

The OP is 100% not about bundling your own stuff... it's simply to understand how MSFT plans to support & update stuff they are going to put on every page as well as what that policy is.

patmill commented 7 years ago

So a cursory test shows that react (at least the latest version of 15.4 and the SPFX version of 14.8) can be loaded onto the same page at the same time and not conflict. Now granted, this was not a deep dive into side-by-side, but nothing is currently barfing on me. My understanding is that you need to make sure to not have the two instances trying to modify the same react dom, but under normal circumstances that shouldn't happen (although we'll need to dive into custom controls in the property pane). Also - please don't take this as a published statement stating exactly the state of the world and what GA will specify. We will give specific guidance in the next short while.

This is a super useful conversation.

andrewconnell commented 7 years ago

Now that we're at GA can we get an update on this?

In the GA release notes you address how to deal with this scenario with the Office UI Fabric ReactJS, or at least some work you plan to address it.

This is something I've heard from multiple people who are not eager to leverage the version of React that is included on the page by default.

patmill commented 7 years ago

We've got two documents coming in this area. One is the general library versioning story around the code spfx libraries. Another one has to do with fabric, fabric core, office ui fabric react, etc. Should be out in the next day or two.

From: Andrew Connell notifications@github.com Sent: Friday, February 24, 2017 6:42:23 AM To: SharePoint/sp-dev-docs Cc: Pat Miller (SHAREPOINT); Mention Subject: Re: [SharePoint/sp-dev-docs] ISO clarification on SPFx's dependent library versioning & rollout policy (#325)

Now that we're at GA can we get an update on this?

In the GA release notes you address how to deal with this scenario with the Office UI Fabric ReactJS, or at least some work you plan to address it.

This is something I've heard from multiple people who are not eager to leverage the version of React that is included on the page by default.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FSharePoint%2Fsp-dev-docs%2Fissues%2F325%23issuecomment-282307685&data=02%7C01%7CPat.Miller%40microsoft.com%7C5b2ac1f88b5543866e5408d45cc359c5%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636235441474138789&sdata=vBncL8GTqeOWzbenkdxwky8adtqZuN9hixGDGFJt%2Bp4%3D&reserved=0, or mute the threadhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FADl-Sa2Ay82EocbEgLflsDG__BFpRjURks5rfuxPgaJpZM4LUGRX&data=02%7C01%7CPat.Miller%40microsoft.com%7C5b2ac1f88b5543866e5408d45cc359c5%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636235441474138789&sdata=KbttgHyUZ6CNinVDPyxh3Fhb4KdjyVOel2ucJGFOr4U%3D&reserved=0.

dcu-sharepoint commented 7 years ago

@andrewconnell Your point is well taken, however, I would like to add a bit of probably off topic matter, meaning support. @shaipetel mentioned something about unskilled developers.

Trust me, there will be tons of us unskilled developers getting intro trouble with versioning with React and more, so the main question here is "what about support?" where do we got to? (besides hell!) and who can we talk to?

For some of us, this stuff is not so obvious or clear cut and no matter how many documents you put out there, there will be a need for a community willing to answer newbe questions without sending us to StackOverflow where one needs a Harvard degree to study their question process to ask questions from their site otherwise risking their wrath and not get an answer to naive questions from unskilled developers trying to get their skill levels up with this beautiful technology ...

My apologies if this is out of topic.

andrewconnell commented 7 years ago

To be fair, there’s nothing unique to SharePoint, SharePoint Framework or ReactJS on that topic.

andrewconnell commented 7 years ago

Did these two docs get published? Looking back through the PR's since GA & in the docs I can't seem to find them. Any update @patmill ?

patmill commented 7 years ago

First take is here - https://github.com/SharePoint/sp-dev-docs/wiki/SPFX-and-Library-Versioning

Fabric story is almost finalized. We will document the approach, then get the code out.

andrewconnell commented 7 years ago

Thanks @patmill... I saw that, but what about libraries you (MSFT / SPFx) are putting on the page that developers can expect to be there... things like React (in addition to Fabric like you mentioned)?

shaipetel commented 7 years ago

@patmill exactly, and stuff like Fabric JS. I just opened another issue that adding any version of Fabric JS components CSS completley breaks the tool pane (drop downs don't open, buttons text looks wierd, etc). The answer I got was a bit shocking: "Fabric Components is obsolete, and not supported in SPFx"...

@andrewconnell brought up a very important issue that if we don't have a clear message now we will pay for it in the short future, when more and more people start building on this framework.

I for one have a product ready to ship within 1-2 weeks and had to completely rename the entire fabric/components CSS+JS files in order to make sure it doesn't conflict with the fabric SPFx is loading to the page (Bye ms-Label, hello kw-Label).

For now I know it is not ideal but I recommend anyone who wants to go live, just make a copy and rename your version to something unique.

patmill commented 7 years ago

Fabric guidance will be out by end of week. @shaipetel - you've basically described the issue - overwriting globals suck, and we need to make sure that the app doesn't clobber customizations, and customizations don't clobber the app.

shaipetel commented 7 years ago

@patmill any updates on fabric? Linking @srideshpande who is assisting on this related issue: https://github.com/SharePoint/sp-dev-docs/issues/434

shaipetel commented 7 years ago

Anyone following this thread for fabric components, I created a service you can use to generate office ui fabric js files with your own custom prefix: https://apps.kwizcom.com/libs/office-ui-fabric-js/1.4.0/css/fabric.css?prefix=kw https://apps.kwizcom.com/libs/office-ui-fabric-js/1.4.0/css/fabric.components.css?prefix=kw https://apps.kwizcom.com/libs/office-ui-fabric-js/1.4.0/js/fabric.js?prefix=kw

Feel free to use it as a CDN, or use it once to generate the file for you. Read more about using it in my blog. Currently I don't see any other way around it. If this becomes popular and people use it, I can do the same for other versions and other libraries, hoping this will help us overcome the globals name conflicts (when we need to use globals).

andrewconnell commented 7 years ago

Bump... this was opened in December 2016, leading up to GA I was under the impression that it was something that was seen as important by the team and would have guidance out on this around GA... but now we're many months past that.

With FP2 coming later this year, it sure would be nice to have an answer for customers asking about this... not just for SPO, but for on-prem.

While @patmill pointed to a doc in the wiki, there's no mention in that doc of MSFT's stance on refreshing dependent libraries... NOT in the toolchain, but on the page.

Let me be blunt: I'm asking about the stance for updating to newer versions of ReactJS

CharlieDLee commented 7 years ago

Further to this I can clarify that this is a very real issue. A recent update to one of my customers tenancies included an update to the Fabric Core classes (including utility classes which encapsulate the Office UI grid system). This was a breaking change and caused all the layout of our production web parts to be compromised. This change has thankfully been reverted, but keeping out of date dependencies is most certainly not the right answer long term. I am waiting eagerly for guidance on what we should be doing in this space.

VesaJuvonen commented 2 years ago

We are going through and cleaning old issues now to do full reset on the development support for SPFx in this issue list. Since the 2017, we have provided updated guidance on this area, but in short the approach is following:

If there's any further questions on this, let's open up a new issue(s), so that we can address updated questions. Thx.

ghost commented 2 years ago

Issues that have been closed & had no follow-up activity for at least 7 days are automatically locked. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: Issue List: Our approach to locked issues