search

stoplightio / elements

Build beautiful, interactive API Docs with embeddable React or Web Components, powered by OpenAPI and Markdown.
https://stoplight.io/open-source/elements/
Apache License 2.0
1.79k stars 205 forks source link

How to use scripts with fixed version? #2018

Open rpascalsdl opened 2 years ago

rpascalsdl commented 2 years ago

Summary

This is a question/suggestion.

While trying to migrate to Elements Dev Portal, DevOps raised a concern that we are including a script (from a CDN) in our web site that is not versioned or verified using a hash. That opens us to potential issues - stuff breaking, or worse..

After checking the CDN versions, we managed to force a specific version and to check for hash. We run the code on a test env first, after which we promote to prod. But now we are concerned that something might change in a new version that will break the functionality of the previous version script (ex - you change back-end and the scripts, which would work transparently for anyone using latest version).

A number of questions:

  1. your take on that subject?
  2. Is there any guarantee you won't make any breaking changes that would require a new script version immediately? (just between 2 versions, I don't expect backwards compatibility forever.)
  3. Is there any way we can track automatically when a new version is out? (email notifications, webhooks, twitter etc.; so we are never more then 1 version behind)
jamietanna commented 2 years ago

The package @stoplight/elements-web-components contains the built version of the CSS + JS, so you should be able to distribute that with the web application that you're hosting, then you can pin to a specific version

jamietanna commented 2 years ago

To amend the above - https://unpkg.com/browse/@stoplight/elements@7.5.12/web-components/ is probably the better solution, rather than the standalone package as above, as it appears to be more recent?

mnaumanali94 commented 2 years ago

@mallachari @mnaumanali94 Lets collaborate with @pamgoodrich on this.