Skip to content

Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469

Closed
Closed
Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469

Description

@chriddyp
chriddyp
opened on Nov 26, 2018

##Roadmap Items

React 16 support

New features and changes

Sign-off as Release Candidate

Deferred

This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.

Proposed list of breaking changes

  1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
  2. Set serve_locally = True by default
  3. Resource integrity checks for CDN resources
  4. Hide the undo/redo buttons by default
  5. Update how the initialization callbacks work if properties aren't supplied

Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1

Technical Background
Dash's front-end is built on top of React.js. This includes:

  • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
  • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.

dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.

Pull Requests that make these changes

Reason for Upgrade

  • React 15 is over 1 year old and React 17 is already on its way.
  • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
  • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
  • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.

Implications for the Dash Developer

  • The Dash Developers will not need to make any changes to their code.
  • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
  • Most developers are not using custom components and therefore will not be affected by this change.

Implications for the Dash Component Author

  • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
  • The most common change is to change the PropTypes import.
    In React 15, this usually looks like: 
    importReact,{PropTypes}from'react';
    In React 16, this is a separate package: 
    importReactfrom'react';importPropTypesfrom'prop-types';
  • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
  • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
importdash_rendererdash_renderer._set_react_version('16.2.0')

We should update dash-renderer with an option to try out React 16.6.1.

Implications for Documentation

Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.

Implications for Community Forum

The following threads mention React and will need to be updated:

I searched "React 16" and "React 15" in the community forum to find these threads.

Will this break or change in the future? If so, how can we prepare?

Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.

For this to be a smooth transition, we should:

  • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
  • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible

Can this be done in a backwards compatible way instead?

No. There is only one React version that is included in Dash and that version needs to be upgraded.

Are there any other risks to consider?

Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).

If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.

We will rely on users to report these issues via the Dash Community Forum.

Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?

  • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
  • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.

Can we automate the upgrade process for our users?

Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).

Is there anything to consider with respect to compatibility between components?

Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.

If something breaks, can we inform users through an error message in any way?

I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.

Are there any open items?

  • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
  • Dash User Guide PRs need to be made
  • Dash Component Boilerplate PRs need to be made
  • Dash
  • I'd like for us to investigate what the common JS error messages are and determine:
    • Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
    • If not, is there anything we can do to intercept these error messages?

Breaking Change 2 - Set serve_locally = True by default

Pull Requests that make these changes

#722

Reason for Upgrade

By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:

app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True

Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:

  1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
  2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
  3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
  4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).

Implications for the Dash Developer

  • This should not break any Dash apps.
  • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
  • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
  • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
  • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.

Implications for the Dash Component Author

Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.

With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.

Implications for Documentation

Implications for Community Forum

Will this break or change in the future? If so, how can we prepare?

No. Once serve_locally = True should be the default for here on out.

Can this be done in a backwards compatible way instead?

No.

Are there any other risks to consider?

There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.

Beyond the communication policy outlined in #458, are there any other ways
that we can inform our users about this change?

No.

Can we automate the upgrade process for our users?

No.

Is there anything to consider with respect to compatibility between
components?

No. All component libraries should work with serve_locally = False.

If something breaks, can we inform users through an error message in any
way?

Perhaps.

  • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
  • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091

Are there any open items?

Breaking Change 3 - Resource integrity checks for CDN resources

Deferred until a later release and less important since serve_locally is True by default

Pull Requests that make these changes

#442

Reason for Upgrade

Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.

This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
No longer a breaking change since we version-lock the dash core packages.

Implications for the Dash Developer

serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).

Implications for the Dash Component Author

Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.

Implications for Documentation

We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate

Implications for Community Forum

None.

Will this break or change in the future? If so, how can we prepare?

I don't think so.

Can this be done in a backwards compatible way instead?

No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
Version locking has rendered this obsolete.

Are there any other risks to consider?

I don't think so.

Beyond the communication policy outlined in #458, are there any other ways
that we can inform our users about this change?

I don't think so.

Can we automate the upgrade process for our users?

Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?

Is there anything to consider with respect to compatibility between
components?

No

If something breaks, can we inform users through an error message in any
way?

If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.

Are there any open items?

  • We will need to document this in our plugin guide: https://github.com/plotly/dash-
  • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
  • Update dash debugging guide with a section about integrity network checks?

Breaking Change 4 - Hide the undo/redo buttons by default

Pull Requests that make these changes

NA

Reason for Upgrade

Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?

It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.

While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.

So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).

Implications for the Dash Developer

If users really liked this feature, then they'll have to explicitly turn it back on.

Implications for the Dash Component Author

None.

Implications for Documentation

  • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
  • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.

Implications for Community Forum

Will this break or change in the future? If so, how can we prepare?

I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.

Can this be done in a backwards compatible way instead?

No.

Are there any other risks to consider?

I don't think so.

Beyond the communication policy outlined in #458, are there any other ways
that we can inform our users about this change?

We should create a new community forum topic outlining the change and specifying how turn this back on.

Can we automate the upgrade process for our users?

No.

Is there anything to consider with respect to compatibility between
components?

No.

If something breaks, can we inform users through an error message in any
way?

No.

Are there any open items?

Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied

This has been deferred until later

For more details, see #468

A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.

Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

    , 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
     blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Dash 1.0.0 Series - Proposed Set of *Breaking Changes* · Issue #469 · plotly/dash · GitHub
    Skip to content
    Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469
    Closed
    Closed
    Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469
    Description
    @chriddyp
    chriddyp
    opened on Nov 26, 2018
    ##Roadmap Items
    React 16 support
    New features and changes
    Sign-off as Release Candidate
    Deferred
    This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
    
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
    
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.
    Proposed list of breaking changes
    1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
    2. Set serve_locally = True by default
    3. Resource integrity checks for CDN resources
    4. Hide the undo/redo buttons by default
    5. Update how the initialization callbacks work if properties aren't supplied
    Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1
    Technical Background
    
Dash's front-end is built on top of React.js. This includes:
    • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
    • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.
    dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.
    Pull Requests that make these changes
    Reason for Upgrade
    • React 15 is over 1 year old and React 17 is already on its way.
    • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
    • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
    • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.
    Implications for the Dash Developer
    • The Dash Developers will not need to make any changes to their code.
    • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
    • Most developers are not using custom components and therefore will not be affected by this change.
    Implications for the Dash Component Author
    • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
    • The most common change is to change the PropTypes import.
      
In React 15, this usually looks like:

      importReact,{PropTypes}from'react';
      
In React 16, this is a separate package:

      importReactfrom'react';importPropTypesfrom'prop-types';
    • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
    • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
    importdash_rendererdash_renderer._set_react_version('16.2.0')
    We should update dash-renderer with an option to try out React 16.6.1.
    Implications for Documentation
    Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.
    Implications for Community Forum
    The following threads mention React and will need to be updated:
    I searched "React 16" and "React 15" in the community forum to find these threads.
    Will this break or change in the future? If so, how can we prepare?
    Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.
    For this to be a smooth transition, we should:
    • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
    • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible
    Can this be done in a backwards compatible way instead?
    No. There is only one React version that is included in Dash and that version needs to be upgraded.
    Are there any other risks to consider?
    Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).
    If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.
    We will rely on users to report these issues via the Dash Community Forum.
    Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?
    • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
    • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.
    Can we automate the upgrade process for our users?
    Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).
    Is there anything to consider with respect to compatibility between components?
    Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.
    If something breaks, can we inform users through an error message in any way?
    I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.
    Are there any open items?
    • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
    •  Dash User Guide PRs need to be made
    •  Dash Component Boilerplate PRs need to be made
    •  Dash
    •  I'd like for us to investigate what the common JS error messages are and determine:

      •  Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
      •  If not, is there anything we can do to intercept these error messages?
    Breaking Change 2 - Set serve_locally = True by default
    Pull Requests that make these changes
    #722
    Reason for Upgrade
    By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:
    app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True
    Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:
    1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
    2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
    3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
    4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).
    Implications for the Dash Developer
    • This should not break any Dash apps.
    • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
    • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
    • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
    • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.
    Implications for the Dash Component Author
    Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.
    With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.
    Implications for Documentation
    Implications for Community Forum
    Will this break or change in the future? If so, how can we prepare?
    No. Once serve_locally = True should be the default for here on out.
    Can this be done in a backwards compatible way instead?
    No.
    Are there any other risks to consider?
    There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.
    Beyond the communication policy outlined in #458, are there any other ways
    
that we can inform our users about this change?
    No.
    Can we automate the upgrade process for our users?
    No.
    Is there anything to consider with respect to compatibility between
    
components?
    No. All component libraries should work with serve_locally = False.
    If something breaks, can we inform users through an error message in any
    
way?
    Perhaps.
    • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
    • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091
    Are there any open items?
    Breaking Change 3 - Resource integrity checks for CDN resources
    Deferred until a later release and less important since serve_locally is True by default
    Pull Requests that make these changes
    #442
    Reason for Upgrade
    Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.
    This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
    
No longer a breaking change since we version-lock the dash core packages.
    Implications for the Dash Developer
    serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).
    Implications for the Dash Component Author
    Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.
    Implications for Documentation
    We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate
    Implications for Community Forum
    None.
    Will this break or change in the future? If so, how can we prepare?
    I don't think so.
    Can this be done in a backwards compatible way instead?
    No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
    
Version locking has rendered this obsolete.
    Are there any other risks to consider?
    I don't think so.
    Beyond the communication policy outlined in #458, are there any other ways
    
that we can inform our users about this change?
    I don't think so.
    Can we automate the upgrade process for our users?
    Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
    Is there anything to consider with respect to compatibility between
    
components?
    No
    If something breaks, can we inform users through an error message in any
    
way?
    If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.
    Are there any open items?
    • We will need to document this in our plugin guide: https://github.com/plotly/dash-
    • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
    • Update dash debugging guide with a section about integrity network checks?
    Breaking Change 4 - Hide the undo/redo buttons by default
    Pull Requests that make these changes
    NA
    Reason for Upgrade
    Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?
    It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.
    While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.
    So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).
    Implications for the Dash Developer
    If users really liked this feature, then they'll have to explicitly turn it back on.
    Implications for the Dash Component Author
    None.
    Implications for Documentation
    • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
    • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.
    Implications for Community Forum
    Will this break or change in the future? If so, how can we prepare?
    I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.
    Can this be done in a backwards compatible way instead?
    No.
    Are there any other risks to consider?
    I don't think so.
    Beyond the communication policy outlined in #458, are there any other ways
    
that we can inform our users about this change?
    We should create a new community forum topic outlining the change and specifying how turn this back on.
    Can we automate the upgrade process for our users?
    No.
    Is there anything to consider with respect to compatibility between
    
components?
    No.
    If something breaks, can we inform users through an error message in any
    
way?
    No.
    Are there any open items?
    Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied
    This has been deferred until later
    For more details, see #468
    A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.
    Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/
    Metadata
    Metadata
    Assignees
    No one assigned
      Labels
      No labels
      No labels
      Type
      No type
      Projects
      No projects
      Milestone
      No milestone
      Relationships
      None yet
      Development
      No branches or pull requests
      Issue actions
      
, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Dash 1.0.0 Series - Proposed Set of *Breaking Changes* · Issue #469 · plotly/dash · GitHub
      Skip to content
      Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469
      Closed
      Closed
      Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469
      Description
      @chriddyp
      chriddyp
      opened on Nov 26, 2018
      ##Roadmap Items
      React 16 support
      New features and changes
      Sign-off as Release Candidate
      Deferred
      This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
      
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
      
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.
      Proposed list of breaking changes
      1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
      2. Set serve_locally = True by default
      3. Resource integrity checks for CDN resources
      4. Hide the undo/redo buttons by default
      5. Update how the initialization callbacks work if properties aren't supplied
      Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1
      Technical Background
      
Dash's front-end is built on top of React.js. This includes:
      • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
      • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.
      dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.
      Pull Requests that make these changes
      Reason for Upgrade
      • React 15 is over 1 year old and React 17 is already on its way.
      • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
      • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
      • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.
      Implications for the Dash Developer
      • The Dash Developers will not need to make any changes to their code.
      • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
      • Most developers are not using custom components and therefore will not be affected by this change.
      Implications for the Dash Component Author
      • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
      • The most common change is to change the PropTypes import.
        
In React 15, this usually looks like:

        importReact,{PropTypes}from'react';
        
In React 16, this is a separate package:

        importReactfrom'react';importPropTypesfrom'prop-types';
      • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
      • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
      importdash_rendererdash_renderer._set_react_version('16.2.0')
      We should update dash-renderer with an option to try out React 16.6.1.
      Implications for Documentation
      Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.
      Implications for Community Forum
      The following threads mention React and will need to be updated:
      I searched "React 16" and "React 15" in the community forum to find these threads.
      Will this break or change in the future? If so, how can we prepare?
      Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.
      For this to be a smooth transition, we should:
      • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
      • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible
      Can this be done in a backwards compatible way instead?
      No. There is only one React version that is included in Dash and that version needs to be upgraded.
      Are there any other risks to consider?
      Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).
      If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.
      We will rely on users to report these issues via the Dash Community Forum.
      Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?
      • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
      • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.
      Can we automate the upgrade process for our users?
      Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).
      Is there anything to consider with respect to compatibility between components?
      Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.
      If something breaks, can we inform users through an error message in any way?
      I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.
      Are there any open items?
      • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
      •  Dash User Guide PRs need to be made
      •  Dash Component Boilerplate PRs need to be made
      •  Dash
      •  I'd like for us to investigate what the common JS error messages are and determine:

        •  Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
        •  If not, is there anything we can do to intercept these error messages?
      Breaking Change 2 - Set serve_locally = True by default
      Pull Requests that make these changes
      #722
      Reason for Upgrade
      By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:
      app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True
      Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:
      1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
      2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
      3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
      4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).
      Implications for the Dash Developer
      • This should not break any Dash apps.
      • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
      • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
      • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
      • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.
      Implications for the Dash Component Author
      Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.
      With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.
      Implications for Documentation
      Implications for Community Forum
      Will this break or change in the future? If so, how can we prepare?
      No. Once serve_locally = True should be the default for here on out.
      Can this be done in a backwards compatible way instead?
      No.
      Are there any other risks to consider?
      There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.
      Beyond the communication policy outlined in #458, are there any other ways
      
that we can inform our users about this change?
      No.
      Can we automate the upgrade process for our users?
      No.
      Is there anything to consider with respect to compatibility between
      
components?
      No. All component libraries should work with serve_locally = False.
      If something breaks, can we inform users through an error message in any
      
way?
      Perhaps.
      • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
      • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091
      Are there any open items?
      Breaking Change 3 - Resource integrity checks for CDN resources
      Deferred until a later release and less important since serve_locally is True by default
      Pull Requests that make these changes
      #442
      Reason for Upgrade
      Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.
      This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
      
No longer a breaking change since we version-lock the dash core packages.
      Implications for the Dash Developer
      serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).
      Implications for the Dash Component Author
      Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.
      Implications for Documentation
      We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate
      Implications for Community Forum
      None.
      Will this break or change in the future? If so, how can we prepare?
      I don't think so.
      Can this be done in a backwards compatible way instead?
      No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
      
Version locking has rendered this obsolete.
      Are there any other risks to consider?
      I don't think so.
      Beyond the communication policy outlined in #458, are there any other ways
      
that we can inform our users about this change?
      I don't think so.
      Can we automate the upgrade process for our users?
      Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
      Is there anything to consider with respect to compatibility between
      
components?
      No
      If something breaks, can we inform users through an error message in any
      
way?
      If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.
      Are there any open items?
      • We will need to document this in our plugin guide: https://github.com/plotly/dash-
      • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
      • Update dash debugging guide with a section about integrity network checks?
      Breaking Change 4 - Hide the undo/redo buttons by default
      Pull Requests that make these changes
      NA
      Reason for Upgrade
      Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?
      It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.
      While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.
      So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).
      Implications for the Dash Developer
      If users really liked this feature, then they'll have to explicitly turn it back on.
      Implications for the Dash Component Author
      None.
      Implications for Documentation
      • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
      • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.
      Implications for Community Forum
      Will this break or change in the future? If so, how can we prepare?
      I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.
      Can this be done in a backwards compatible way instead?
      No.
      Are there any other risks to consider?
      I don't think so.
      Beyond the communication policy outlined in #458, are there any other ways
      
that we can inform our users about this change?
      We should create a new community forum topic outlining the change and specifying how turn this back on.
      Can we automate the upgrade process for our users?
      No.
      Is there anything to consider with respect to compatibility between
      
components?
      No.
      If something breaks, can we inform users through an error message in any
      
way?
      No.
      Are there any open items?
      Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied
      This has been deferred until later
      For more details, see #468
      A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.
      Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/
      Metadata
      Metadata
      Assignees
      No one assigned
        Labels
        No labels
        No labels
        Type
        No type
        Projects
        No projects
        Milestone
        No milestone
        Relationships
        None yet
        Development
        No branches or pull requests
        Issue actions
        
, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Dash 1.0.0 Series - Proposed Set of *Breaking Changes* · Issue #469 · plotly/dash · GitHub
        Skip to content
        Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469
        Closed
        Closed
        Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469
        Description
        @chriddyp
        chriddyp
        opened on Nov 26, 2018
        ##Roadmap Items
        React 16 support
        New features and changes
        Sign-off as Release Candidate
        Deferred
        This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
        
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
        
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.
        Proposed list of breaking changes
        1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
        2. Set serve_locally = True by default
        3. Resource integrity checks for CDN resources
        4. Hide the undo/redo buttons by default
        5. Update how the initialization callbacks work if properties aren't supplied
        Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1
        Technical Background
        
Dash's front-end is built on top of React.js. This includes:
        • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
        • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.
        dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.
        Pull Requests that make these changes
        Reason for Upgrade
        • React 15 is over 1 year old and React 17 is already on its way.
        • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
        • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
        • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.
        Implications for the Dash Developer
        • The Dash Developers will not need to make any changes to their code.
        • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
        • Most developers are not using custom components and therefore will not be affected by this change.
        Implications for the Dash Component Author
        • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
        • The most common change is to change the PropTypes import.
          
In React 15, this usually looks like:

          importReact,{PropTypes}from'react';
          
In React 16, this is a separate package:

          importReactfrom'react';importPropTypesfrom'prop-types';
        • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
        • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
        importdash_rendererdash_renderer._set_react_version('16.2.0')
        We should update dash-renderer with an option to try out React 16.6.1.
        Implications for Documentation
        Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.
        Implications for Community Forum
        The following threads mention React and will need to be updated:
        I searched "React 16" and "React 15" in the community forum to find these threads.
        Will this break or change in the future? If so, how can we prepare?
        Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.
        For this to be a smooth transition, we should:
        • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
        • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible
        Can this be done in a backwards compatible way instead?
        No. There is only one React version that is included in Dash and that version needs to be upgraded.
        Are there any other risks to consider?
        Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).
        If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.
        We will rely on users to report these issues via the Dash Community Forum.
        Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?
        • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
        • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.
        Can we automate the upgrade process for our users?
        Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).
        Is there anything to consider with respect to compatibility between components?
        Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.
        If something breaks, can we inform users through an error message in any way?
        I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.
        Are there any open items?
        • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
        •  Dash User Guide PRs need to be made
        •  Dash Component Boilerplate PRs need to be made
        •  Dash
        •  I'd like for us to investigate what the common JS error messages are and determine:

          •  Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
          •  If not, is there anything we can do to intercept these error messages?
        Breaking Change 2 - Set serve_locally = True by default
        Pull Requests that make these changes
        #722
        Reason for Upgrade
        By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:
        app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True
        Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:
        1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
        2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
        3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
        4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).
        Implications for the Dash Developer
        • This should not break any Dash apps.
        • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
        • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
        • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
        • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.
        Implications for the Dash Component Author
        Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.
        With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.
        Implications for Documentation
        Implications for Community Forum
        Will this break or change in the future? If so, how can we prepare?
        No. Once serve_locally = True should be the default for here on out.
        Can this be done in a backwards compatible way instead?
        No.
        Are there any other risks to consider?
        There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.
        Beyond the communication policy outlined in #458, are there any other ways
        
that we can inform our users about this change?
        No.
        Can we automate the upgrade process for our users?
        No.
        Is there anything to consider with respect to compatibility between
        
components?
        No. All component libraries should work with serve_locally = False.
        If something breaks, can we inform users through an error message in any
        
way?
        Perhaps.
        • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
        • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091
        Are there any open items?
        Breaking Change 3 - Resource integrity checks for CDN resources
        Deferred until a later release and less important since serve_locally is True by default
        Pull Requests that make these changes
        #442
        Reason for Upgrade
        Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.
        This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
        
No longer a breaking change since we version-lock the dash core packages.
        Implications for the Dash Developer
        serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).
        Implications for the Dash Component Author
        Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.
        Implications for Documentation
        We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate
        Implications for Community Forum
        None.
        Will this break or change in the future? If so, how can we prepare?
        I don't think so.
        Can this be done in a backwards compatible way instead?
        No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
        
Version locking has rendered this obsolete.
        Are there any other risks to consider?
        I don't think so.
        Beyond the communication policy outlined in #458, are there any other ways
        
that we can inform our users about this change?
        I don't think so.
        Can we automate the upgrade process for our users?
        Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
        Is there anything to consider with respect to compatibility between
        
components?
        No
        If something breaks, can we inform users through an error message in any
        
way?
        If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.
        Are there any open items?
        • We will need to document this in our plugin guide: https://github.com/plotly/dash-
        • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
        • Update dash debugging guide with a section about integrity network checks?
        Breaking Change 4 - Hide the undo/redo buttons by default
        Pull Requests that make these changes
        NA
        Reason for Upgrade
        Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?
        It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.
        While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.
        So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).
        Implications for the Dash Developer
        If users really liked this feature, then they'll have to explicitly turn it back on.
        Implications for the Dash Component Author
        None.
        Implications for Documentation
        • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
        • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.
        Implications for Community Forum
        Will this break or change in the future? If so, how can we prepare?
        I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.
        Can this be done in a backwards compatible way instead?
        No.
        Are there any other risks to consider?
        I don't think so.
        Beyond the communication policy outlined in #458, are there any other ways
        
that we can inform our users about this change?
        We should create a new community forum topic outlining the change and specifying how turn this back on.
        Can we automate the upgrade process for our users?
        No.
        Is there anything to consider with respect to compatibility between
        
components?
        No.
        If something breaks, can we inform users through an error message in any
        
way?
        No.
        Are there any open items?
        Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied
        This has been deferred until later
        For more details, see #468
        A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.
        Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/
        Metadata
        Metadata
        Assignees
        No one assigned
          Labels
          No labels
          No labels
          Type
          No type
          Projects
          No projects
          Milestone
          No milestone
          Relationships
          None yet
          Development
          No branches or pull requests
          Issue actions
          
, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
Dash 1.0.0 Series - Proposed Set of *Breaking Changes* · Issue #469 · plotly/dash · GitHub
          Skip to content
          Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469
          Closed
          Closed
          Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469
          Description
          @chriddyp
          chriddyp
          opened on Nov 26, 2018
          ##Roadmap Items
          React 16 support
          New features and changes
          Sign-off as Release Candidate
          Deferred
          This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
          
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
          
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.
          Proposed list of breaking changes
          1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
          2. Set serve_locally = True by default
          3. Resource integrity checks for CDN resources
          4. Hide the undo/redo buttons by default
          5. Update how the initialization callbacks work if properties aren't supplied
          Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1
          Technical Background
          
Dash's front-end is built on top of React.js. This includes:
          • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
          • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.
          dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.
          Pull Requests that make these changes
          Reason for Upgrade
          • React 15 is over 1 year old and React 17 is already on its way.
          • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
          • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
          • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.
          Implications for the Dash Developer
          • The Dash Developers will not need to make any changes to their code.
          • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
          • Most developers are not using custom components and therefore will not be affected by this change.
          Implications for the Dash Component Author
          • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
          • The most common change is to change the PropTypes import.
            
In React 15, this usually looks like:

            importReact,{PropTypes}from'react';
            
In React 16, this is a separate package:

            importReactfrom'react';importPropTypesfrom'prop-types';
          • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
          • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
          importdash_rendererdash_renderer._set_react_version('16.2.0')
          We should update dash-renderer with an option to try out React 16.6.1.
          Implications for Documentation
          Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.
          Implications for Community Forum
          The following threads mention React and will need to be updated:
          I searched "React 16" and "React 15" in the community forum to find these threads.
          Will this break or change in the future? If so, how can we prepare?
          Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.
          For this to be a smooth transition, we should:
          • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
          • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible
          Can this be done in a backwards compatible way instead?
          No. There is only one React version that is included in Dash and that version needs to be upgraded.
          Are there any other risks to consider?
          Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).
          If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.
          We will rely on users to report these issues via the Dash Community Forum.
          Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?
          • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
          • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.
          Can we automate the upgrade process for our users?
          Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).
          Is there anything to consider with respect to compatibility between components?
          Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.
          If something breaks, can we inform users through an error message in any way?
          I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.
          Are there any open items?
          • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
          •  Dash User Guide PRs need to be made
          •  Dash Component Boilerplate PRs need to be made
          •  Dash
          •  I'd like for us to investigate what the common JS error messages are and determine:

            •  Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
            •  If not, is there anything we can do to intercept these error messages?
          Breaking Change 2 - Set serve_locally = True by default
          Pull Requests that make these changes
          #722
          Reason for Upgrade
          By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:
          app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True
          Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:
          1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
          2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
          3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
          4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).
          Implications for the Dash Developer
          • This should not break any Dash apps.
          • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
          • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
          • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
          • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.
          Implications for the Dash Component Author
          Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.
          With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.
          Implications for Documentation
          Implications for Community Forum
          Will this break or change in the future? If so, how can we prepare?
          No. Once serve_locally = True should be the default for here on out.
          Can this be done in a backwards compatible way instead?
          No.
          Are there any other risks to consider?
          There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.
          Beyond the communication policy outlined in #458, are there any other ways
          
that we can inform our users about this change?
          No.
          Can we automate the upgrade process for our users?
          No.
          Is there anything to consider with respect to compatibility between
          
components?
          No. All component libraries should work with serve_locally = False.
          If something breaks, can we inform users through an error message in any
          
way?
          Perhaps.
          • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
          • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091
          Are there any open items?
          Breaking Change 3 - Resource integrity checks for CDN resources
          Deferred until a later release and less important since serve_locally is True by default
          Pull Requests that make these changes
          #442
          Reason for Upgrade
          Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.
          This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
          
No longer a breaking change since we version-lock the dash core packages.
          Implications for the Dash Developer
          serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).
          Implications for the Dash Component Author
          Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.
          Implications for Documentation
          We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate
          Implications for Community Forum
          None.
          Will this break or change in the future? If so, how can we prepare?
          I don't think so.
          Can this be done in a backwards compatible way instead?
          No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
          
Version locking has rendered this obsolete.
          Are there any other risks to consider?
          I don't think so.
          Beyond the communication policy outlined in #458, are there any other ways
          
that we can inform our users about this change?
          I don't think so.
          Can we automate the upgrade process for our users?
          Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
          Is there anything to consider with respect to compatibility between
          
components?
          No
          If something breaks, can we inform users through an error message in any
          
way?
          If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.
          Are there any open items?
          • We will need to document this in our plugin guide: https://github.com/plotly/dash-
          • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
          • Update dash debugging guide with a section about integrity network checks?
          Breaking Change 4 - Hide the undo/redo buttons by default
          Pull Requests that make these changes
          NA
          Reason for Upgrade
          Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?
          It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.
          While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.
          So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).
          Implications for the Dash Developer
          If users really liked this feature, then they'll have to explicitly turn it back on.
          Implications for the Dash Component Author
          None.
          Implications for Documentation
          • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
          • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.
          Implications for Community Forum
          Will this break or change in the future? If so, how can we prepare?
          I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.
          Can this be done in a backwards compatible way instead?
          No.
          Are there any other risks to consider?
          I don't think so.
          Beyond the communication policy outlined in #458, are there any other ways
          
that we can inform our users about this change?
          We should create a new community forum topic outlining the change and specifying how turn this back on.
          Can we automate the upgrade process for our users?
          No.
          Is there anything to consider with respect to compatibility between
          
components?
          No.
          If something breaks, can we inform users through an error message in any
          
way?
          No.
          Are there any open items?
          Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied
          This has been deferred until later
          For more details, see #468
          A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.
          Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/
          Metadata
          Metadata
          Assignees
          No one assigned
            Labels
            No labels
            No labels
            Type
            No type
            Projects
            No projects
            Milestone
            No milestone
            Relationships
            None yet
            Development
            No branches or pull requests
            Issue actions
            
, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Dash 1.0.0 Series - Proposed Set of *Breaking Changes* · Issue #469 · plotly/dash · GitHub
            Skip to content
            Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469
            Closed
            Closed
            Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469
            Description
            @chriddyp
            chriddyp
            opened on Nov 26, 2018
            ##Roadmap Items
            React 16 support
            New features and changes
            Sign-off as Release Candidate
            Deferred
            This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
            
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
            
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.
            Proposed list of breaking changes
            1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
            2. Set serve_locally = True by default
            3. Resource integrity checks for CDN resources
            4. Hide the undo/redo buttons by default
            5. Update how the initialization callbacks work if properties aren't supplied
            Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1
            Technical Background
            
Dash's front-end is built on top of React.js. This includes:
            • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
            • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.
            dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.
            Pull Requests that make these changes
            Reason for Upgrade
            • React 15 is over 1 year old and React 17 is already on its way.
            • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
            • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
            • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.
            Implications for the Dash Developer
            • The Dash Developers will not need to make any changes to their code.
            • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
            • Most developers are not using custom components and therefore will not be affected by this change.
            Implications for the Dash Component Author
            • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
            • The most common change is to change the PropTypes import.
              
In React 15, this usually looks like:

              importReact,{PropTypes}from'react';
              
In React 16, this is a separate package:

              importReactfrom'react';importPropTypesfrom'prop-types';
            • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
            • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
            importdash_rendererdash_renderer._set_react_version('16.2.0')
            We should update dash-renderer with an option to try out React 16.6.1.
            Implications for Documentation
            Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.
            Implications for Community Forum
            The following threads mention React and will need to be updated:
            I searched "React 16" and "React 15" in the community forum to find these threads.
            Will this break or change in the future? If so, how can we prepare?
            Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.
            For this to be a smooth transition, we should:
            • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
            • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible
            Can this be done in a backwards compatible way instead?
            No. There is only one React version that is included in Dash and that version needs to be upgraded.
            Are there any other risks to consider?
            Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).
            If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.
            We will rely on users to report these issues via the Dash Community Forum.
            Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?
            • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
            • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.
            Can we automate the upgrade process for our users?
            Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).
            Is there anything to consider with respect to compatibility between components?
            Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.
            If something breaks, can we inform users through an error message in any way?
            I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.
            Are there any open items?
            • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
            •  Dash User Guide PRs need to be made
            •  Dash Component Boilerplate PRs need to be made
            •  Dash
            •  I'd like for us to investigate what the common JS error messages are and determine:

              •  Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
              •  If not, is there anything we can do to intercept these error messages?
            Breaking Change 2 - Set serve_locally = True by default
            Pull Requests that make these changes
            #722
            Reason for Upgrade
            By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:
            app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True
            Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:
            1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
            2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
            3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
            4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).
            Implications for the Dash Developer
            • This should not break any Dash apps.
            • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
            • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
            • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
            • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.
            Implications for the Dash Component Author
            Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.
            With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.
            Implications for Documentation
            Implications for Community Forum
            Will this break or change in the future? If so, how can we prepare?
            No. Once serve_locally = True should be the default for here on out.
            Can this be done in a backwards compatible way instead?
            No.
            Are there any other risks to consider?
            There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.
            Beyond the communication policy outlined in #458, are there any other ways
            
that we can inform our users about this change?
            No.
            Can we automate the upgrade process for our users?
            No.
            Is there anything to consider with respect to compatibility between
            
components?
            No. All component libraries should work with serve_locally = False.
            If something breaks, can we inform users through an error message in any
            
way?
            Perhaps.
            • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
            • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091
            Are there any open items?
            Breaking Change 3 - Resource integrity checks for CDN resources
            Deferred until a later release and less important since serve_locally is True by default
            Pull Requests that make these changes
            #442
            Reason for Upgrade
            Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.
            This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
            
No longer a breaking change since we version-lock the dash core packages.
            Implications for the Dash Developer
            serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).
            Implications for the Dash Component Author
            Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.
            Implications for Documentation
            We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate
            Implications for Community Forum
            None.
            Will this break or change in the future? If so, how can we prepare?
            I don't think so.
            Can this be done in a backwards compatible way instead?
            No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
            
Version locking has rendered this obsolete.
            Are there any other risks to consider?
            I don't think so.
            Beyond the communication policy outlined in #458, are there any other ways
            
that we can inform our users about this change?
            I don't think so.
            Can we automate the upgrade process for our users?
            Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
            Is there anything to consider with respect to compatibility between
            
components?
            No
            If something breaks, can we inform users through an error message in any
            
way?
            If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.
            Are there any open items?
            • We will need to document this in our plugin guide: https://github.com/plotly/dash-
            • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
            • Update dash debugging guide with a section about integrity network checks?
            Breaking Change 4 - Hide the undo/redo buttons by default
            Pull Requests that make these changes
            NA
            Reason for Upgrade
            Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?
            It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.
            While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.
            So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).
            Implications for the Dash Developer
            If users really liked this feature, then they'll have to explicitly turn it back on.
            Implications for the Dash Component Author
            None.
            Implications for Documentation
            • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
            • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.
            Implications for Community Forum
            Will this break or change in the future? If so, how can we prepare?
            I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.
            Can this be done in a backwards compatible way instead?
            No.
            Are there any other risks to consider?
            I don't think so.
            Beyond the communication policy outlined in #458, are there any other ways
            
that we can inform our users about this change?
            We should create a new community forum topic outlining the change and specifying how turn this back on.
            Can we automate the upgrade process for our users?
            No.
            Is there anything to consider with respect to compatibility between
            
components?
            No.
            If something breaks, can we inform users through an error message in any
            
way?
            No.
            Are there any open items?
            Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied
            This has been deferred until later
            For more details, see #468
            A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.
            Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/
            Metadata
            Metadata
            Assignees
            No one assigned
              Labels
              No labels
              No labels
              Type
              No type
              Projects
              No projects
              Milestone
              No milestone
              Relationships
              None yet
              Development
              No branches or pull requests
              Issue actions
              
, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
})();
Dash 1.0.0 Series - Proposed Set of *Breaking Changes* · Issue #469 · plotly/dash · GitHub
              Skip to content
              Dash 1.0.0 Series - Proposed Set of *Breaking Changes* #469
              Closed
              Closed
              Dash 1.0.0 Series - Proposed Set of *Breaking Changes*#469
              Description
              @chriddyp
              chriddyp
              opened on Nov 26, 2018
              ##Roadmap Items
              React 16 support
              New features and changes
              Sign-off as Release Candidate
              Deferred
              This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
              
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
              
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.
              Proposed list of breaking changes
              1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
              2. Set serve_locally = True by default
              3. Resource integrity checks for CDN resources
              4. Hide the undo/redo buttons by default
              5. Update how the initialization callbacks work if properties aren't supplied
              Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1
              Technical Background
              
Dash's front-end is built on top of React.js. This includes:
              • dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
              • The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.
              dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.
              Pull Requests that make these changes
              Reason for Upgrade
              • React 15 is over 1 year old and React 17 is already on its way.
              • Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
              • Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
              • A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.
              Implications for the Dash Developer
              • The Dash Developers will not need to make any changes to their code.
              • If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
              • Most developers are not using custom components and therefore will not be affected by this change.
              Implications for the Dash Component Author
              • Component authors will need to upgrade their JavaScript components to be compatible with React 16.
              • The most common change is to change the PropTypes import.
                
In React 15, this usually looks like:

                importReact,{PropTypes}from'react';
                
In React 16, this is a separate package:

                importReactfrom'react';importPropTypesfrom'prop-types';
              • If the component author is using a 3rd party package, they may need to upgrade the underlying component.
              • To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:
              importdash_rendererdash_renderer._set_react_version('16.2.0')
              We should update dash-renderer with an option to try out React 16.6.1.
              Implications for Documentation
              Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.
              Implications for Community Forum
              The following threads mention React and will need to be updated:
              I searched "React 16" and "React 15" in the community forum to find these threads.
              Will this break or change in the future? If so, how can we prepare?
              Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.
              For this to be a smooth transition, we should:
              • Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
              • Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible
              Can this be done in a backwards compatible way instead?
              No. There is only one React version that is included in Dash and that version needs to be upgraded.
              Are there any other risks to consider?
              Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).
              If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.
              We will rely on users to report these issues via the Dash Community Forum.
              Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?
              • React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
              • Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.
              Can we automate the upgrade process for our users?
              Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).
              Is there anything to consider with respect to compatibility between components?
              Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.
              If something breaks, can we inform users through an error message in any way?
              I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.
              Are there any open items?
              • dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
              •  Dash User Guide PRs need to be made
              •  Dash Component Boilerplate PRs need to be made
              •  Dash
              •  I'd like for us to investigate what the common JS error messages are and determine:

                •  Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
                •  If not, is there anything we can do to intercept these error messages?
              Breaking Change 2 - Set serve_locally = True by default
              Pull Requests that make these changes
              #722
              Reason for Upgrade
              By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:
              app.scripts.config.serve_locally=Trueapp.css.config.serve_locally=True
              Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:
              1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
              2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
              3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
              4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).
              Implications for the Dash Developer
              • This should not break any Dash apps.
              • Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
              • If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
              • Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
              • There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.
              Implications for the Dash Component Author
              Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.
              With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.
              Implications for Documentation
              Implications for Community Forum
              Will this break or change in the future? If so, how can we prepare?
              No. Once serve_locally = True should be the default for here on out.
              Can this be done in a backwards compatible way instead?
              No.
              Are there any other risks to consider?
              There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.
              Beyond the communication policy outlined in #458, are there any other ways
              
that we can inform our users about this change?
              No.
              Can we automate the upgrade process for our users?
              No.
              Is there anything to consider with respect to compatibility between
              
components?
              No. All component libraries should work with serve_locally = False.
              If something breaks, can we inform users through an error message in any
              
way?
              Perhaps.
              • If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
              • We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091
              Are there any open items?
              Breaking Change 3 - Resource integrity checks for CDN resources
              Deferred until a later release and less important since serve_locally is True by default
              Pull Requests that make these changes
              #442
              Reason for Upgrade
              Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.
              This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
              
No longer a breaking change since we version-lock the dash core packages.
              Implications for the Dash Developer
              serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).
              Implications for the Dash Component Author
              Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.
              Implications for Documentation
              We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate
              Implications for Community Forum
              None.
              Will this break or change in the future? If so, how can we prepare?
              I don't think so.
              Can this be done in a backwards compatible way instead?
              No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
              
Version locking has rendered this obsolete.
              Are there any other risks to consider?
              I don't think so.
              Beyond the communication policy outlined in #458, are there any other ways
              
that we can inform our users about this change?
              I don't think so.
              Can we automate the upgrade process for our users?
              Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
              Is there anything to consider with respect to compatibility between
              
components?
              No
              If something breaks, can we inform users through an error message in any
              
way?
              If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.
              Are there any open items?
              • We will need to document this in our plugin guide: https://github.com/plotly/dash-
              • Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
              • Update dash debugging guide with a section about integrity network checks?
              Breaking Change 4 - Hide the undo/redo buttons by default
              Pull Requests that make these changes
              NA
              Reason for Upgrade
              Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?
              It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.
              While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.
              So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).
              Implications for the Dash Developer
              If users really liked this feature, then they'll have to explicitly turn it back on.
              Implications for the Dash Component Author
              None.
              Implications for Documentation
              • We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
              • We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.
              Implications for Community Forum
              Will this break or change in the future? If so, how can we prepare?
              I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.
              Can this be done in a backwards compatible way instead?
              No.
              Are there any other risks to consider?
              I don't think so.
              Beyond the communication policy outlined in #458, are there any other ways
              
that we can inform our users about this change?
              We should create a new community forum topic outlining the change and specifying how turn this back on.
              Can we automate the upgrade process for our users?
              No.
              Is there anything to consider with respect to compatibility between
              
components?
              No.
              If something breaks, can we inform users through an error message in any
              
way?
              No.
              Are there any open items?
              Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied
              This has been deferred until later
              For more details, see #468
              A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.
              Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/
              Metadata
              Metadata
              Assignees
              No one assigned
                Labels
                No labels
                No labels
                Type
                No type
                Projects
                No projects
                Milestone
                No milestone
                Relationships
                None yet
                Development
                No branches or pull requests
                Issue actions