diff --git a/CHANGES.md b/CHANGES.md index ff0f973a..cd9b5868 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,5 +1,6 @@ # ? +- Docs (3.0.0): Clarify - Docs (ReleaseInstructions): Clarify need for npm permissions to publish # 3.1.1 diff --git a/docs/versions/3.0.0.md b/docs/versions/3.0.0.md index 326b59b0..9bf2908a 100644 --- a/docs/versions/3.0.0.md +++ b/docs/versions/3.0.0.md @@ -50,29 +50,29 @@ For ES6 Modules being available as a distribution option, see "Enhancements". ##### Design choices for applying modules (Technical) The jQuery files have not been added in ES6 Modules format, however, because -they do not have such a distribution and adding an import in source would -require compilation whereas we'd like the modular file to work without -compilation for faster debugging (note that rather than importing our -external npm dependencies directly from `node_modules`, we have a `copy-deps` -script for copying these files into our repository, so experimenting on -these files should probably be done within the `editor/external` directory, -though such changes should not be committed unless the source packages -are also updated and the `copy-deps` routine brings them in). +they do not have such a distribution and adding an import in source which +converts them to ES6 Modules through plugin would require compilation +whereas we'd prefer that at least the modular editor file be able to work +without compilation for faster debugging (note, however, that rather than +importing our external npm dependencies directly from `node_modules`, we +have a `copy-deps` script for copying these files into our repository, so +experimenting on these files should probably be done within the +`editor/external` directory and such changes must not be committed unless +the source packages are also updated and the `copy-deps` routine brings them +in). The file `redirect-on-lacking-support.js` has not been bundled with the main `svgedit-config-es.js` script so that browsers not supporting SVG are redirected faster (and, in the same vein as polyfills, it may be more -logically consistent to add this externally anyways). +logically consistent to add this external to the main code anyways). -The `redirect-on-no-module-support.js`, which redirects when module -support is not available, is not bundled for the same essential reason. +The file `redirect-on-no-module-support.js`, which redirects when module +support is not available, is not bundled for the same type of reason. #### JavaScript config file breaking changes -In place of looking for `config.js` in the `editor` directory, - Unlike version 2.8.1 which had a `config-sample.js` file which needed -to be copied to `config.js` in the same directory, in version 3.0.0, +to be copied to `config.js` in the same `editor` directory, in version 3.0.0, things work out of the box by pointing to the pre-built config files (also an advantage for our use of Github-based project hosts like raw.githack.com), but these config files have been moved out of the @@ -80,11 +80,29 @@ raw.githack.com), but these config files have been moved out of the if using the editor within our repository). These files also now have different names (`svgedit-config-es.js` -for `svg-editor-es.html` and `svgedit-config-iife.js` for `svg-editor.html`). +for `svg-editor-es.html` and `svgedit-config-iife.js` for `svg-editor.html`) +for a measure of namespacing. This move is intended to allow config to be stored semi-independently of editor files. +Also note that while the config file was optional in 2.8.1, the config +file in 3.* includes (or for, the ES version, imports) all of the main +SVG-Edit code, so the file (or one like it) cannot be omitted. This has +the advantage of avoiding an extra script tag and for the non-ES version, +an extra HTTP request. But if you are working with the non-modular HTML +and are not running the build routines to compile ES to non-modular +JavaScript, you will be required to directly modify your config within +the large non-modular, bundled JavaScript config file that includes most +of the SVG codebase. + +The build routines include `npm run build-config` to convert the +JavaScript config to non-modular form, `npm run rollup` to convert the other +source files to non-modular form, and `npm run build-html` to build the +non-modular HTML out of the modular HTML (all of these are run during +`npm run test-prep`, or if you want to run the tests, also as a part of +`npm test` and `npm run browser-test`). + #### Stylesheet breaking changes In version 2.8.1, one could place a `custom.css` file in the same directory @@ -96,7 +114,7 @@ and is expected as `svgedit-custom.css`. You may change the stylesheets which are loaded by changing the default JavaScript stylesheet config (see the "JavaScript config file breaking changes" section for the location of -these files). The default is: +these files). The default behavior is equivalent to this: ```js svgEditor.setConfig({ @@ -104,7 +122,7 @@ svgEditor.setConfig({ }); ``` -...which indicates it will load all default stylesheets and then +...which indicates that all default stylesheets will be loaded and then one's custom file. You may omit either of these and/or add your own. See "Other breaking changes -> HTML" for removal of the "scoped" @@ -119,26 +137,28 @@ and in order to avoid path resolution problems, the config properties `extPath` and `langPath` now have different defaults, depending on whether a module environment is detected or not. -The non-modular versions will now default to "../dist/extensions/" and -"../dist/locale/", respectively, whereas the modular version will use the -old default paths ("extensions/" and "locale/"). +The non-modular versions will now default to `../dist/extensions/` and +`../dist/locale/`, respectively, whereas the modular version will use the +old default paths (`extensions/` and `locale/`). Also, since we have not copying extension icons over to `dist` and the path resolution of extension icons would otherwise break, we have now added new -config `extIconsPath`, distinct from `extPath`, which points by default to -"extensions/" for both modular and non-modular environments. +a config property, `extIconsPath`, distinct from `extPath`, which points +by default to `extensions/` for both modular and non-modular environments. -And because canvg and jspdf are now building from module and would break as -a result of this move as well, we have added the config `canvgPath` and -`jspdfPath` which default respectively to "canvg/" and "jspdf/" for modular -loads and to "../dist/" for both path types with non-modular loads. +And because our dependencies canvg and jspdf are now building from module +and would break as a result of this move as well, we have added the config +`canvgPath` and `jspdfPath` which default respectively to `canvg/` and +`jspdf/` in modular loads and to `../dist/` for both path types within +non-modular loads. (`imgPath` and `jGraduatePath` remain unchanged since they, as with -`extIconsPath`, are not looking for module-only files.) +`extIconsPath`, are not looking for module-expressed files.) #### Locale breaking changes -Locale files are now formatted as ES6 Module exports. +Locale files are now formatted as ES6 Module exports (rather than as +calls to `svgEditor.readLang`). In order for their value to be discovered when compiled and loaded in a non-modular context, in such contexts they will be auto-defined @@ -146,22 +166,21 @@ as global variables (as "svgEditorLang_" followed by the locale file name with any hyphens replaced as underscores). In the spirit of modularization and only loading what is needed, - locale strings pertaining solely to extensions were moved to +locale strings pertaining solely to extensions were moved to `editor/extensons/ext-locale//.js`. -A new method, `importLocale`, is passed to extensions -(see "Summary of enhancements -> APIs") which can load locale files -within this hierarchy, requiring no arguments if relying on the detected -locale. +A new method, `importLocale`, is passed to extensions (see +"Summary of enhancements -> APIs") which can load locale files within +this hierarchy, requiring no arguments if relying on the detected locale. -The `npm run rollup` routine (also a part of `npm test`) will build -any properly named and formatted ES6 Modules locale file into a non-modular -file within `dist/locale`. +The `npm run rollup` routine (also a part of `npm run test-prep` or +the full test routines) will build any properly named and formatted ES6 +Modules locale file into a non-modular file within `dist/locale`. #### Extension breaking changes -Extension files are now formatted as ES6 Module exports rather than as -calls to `svgEditor.addExtension`. The latter may still be used, but +Extension files are now formatted as ES6 Module exports (rather than as +calls to `svgEditor.addExtension`). The latter may still be used, but support for passing an object (with a `callback` method as an init function) is not (`callback` may be present on the *return* object of extension `init` method, however). @@ -178,15 +197,15 @@ only used as a unique identifier). Any init function previously supplied as second argument to `addExtension` should be expressed as an `init` method on the object exported by the -extension and it should return what the init function had been returning. +extension, and it should return what the init function had been returning. Its `this` value will be set to the editor object. For the object returned by `init`, invocation of any `callback` method will also be invoked with the `this` value set to the editor object. -The `npm run rollup` routine (also a part of `npm test`) will build -any properly named and formatted ES6 Modules extension file into a non-modular -file within `dist/extensions`. +The `npm run rollup` routine (also a part of `npm run test-prep` or +the full test routines) will build any properly named and formatted ES6 +Modules extension file into a non-modular file within `dist/extensions`. See also "Locale breaking changes".