201 lines
10 KiB
Markdown
201 lines
10 KiB
Markdown
# Development
|
|
|
|
Note that this document goes roughly in order of increasing importance. This
|
|
is done so you can see what is available and also see what scripts may be
|
|
automatically run as part of the later-mentioned items.
|
|
|
|
## Installing/Updating releases
|
|
|
|
In order to allow old versions to be available along with the `master` version
|
|
on our Github Pages-hosted repository, we have added old versions as submodules.
|
|
|
|
Most users will therefore not want to clone recursively, but for developing,
|
|
at least publishing, this may be necessary.
|
|
|
|
- `npm run submodules`
|
|
- `npm run submodules-init`- This is a *non-recursive* init as we don't
|
|
want the submodules themselves to have their own releases!
|
|
(They will have `releases` with subfolders for versions, but
|
|
no contents.)
|
|
- `npm run submodules-update` - Fetches and merges *non-recursively* and
|
|
merges any changes into `master` (e.g., if an unreleased version branch
|
|
was first added but needed more added to it).
|
|
|
|
## Building docs
|
|
|
|
Though the building of docs is automatically run before publishing,
|
|
this may also be useful for reference during testing. Build through
|
|
`npm run build-docs`.
|
|
|
|
To start a server and open already built docs, use `npm run open-docs` (or
|
|
`npm run open-docs-no-start` if you already have a `start` process
|
|
running in another terminal tab).
|
|
|
|
Or to build *and* open the docs, use `npm run build-and-open-docs` (or
|
|
`npm run build-and-open-docs-no-start` if you already have a `start` process
|
|
running in another terminal tab).
|
|
|
|
## Scripts for running after dependency changes
|
|
|
|
1. Copying files. Some `devDependencies` are incorporated into the svgedit
|
|
repository (and npm package) so that Github or npm hosting services
|
|
can run (without needing to take the much heavier step of bundling all of
|
|
`node_modules`).
|
|
1. `npm run copy`
|
|
1. Checking licenses - If updating a dependency or devDependency,
|
|
the project's aggregate license information might change. To get
|
|
this information updated, run:
|
|
1. `npm run license-badges` (Which runs the following commands)
|
|
1. `npm run license-badge` (Only build the license badge containing
|
|
info on this project's license(s) and those of any `dependencies`,
|
|
and the `devDependencies` which are being bundled into the
|
|
repository/npm package.)
|
|
1. `npm run license-badge-dev` (Only build the license badge for this
|
|
project's `devDependencies`. This is probably not of great concern
|
|
unless a project is restrictive in terms of usage--i.e., if a
|
|
dependency is not what is typically considered "open" source.)
|
|
|
|
The above are run before publishing, but they should be checked whenever
|
|
updating dependencies ([`npm-check-updates`](https://github.com/tjunnone/npm-check-updates)
|
|
is recommended, especially as our repo is configured to ignore updating
|
|
those packages which shouldn't be updated (see `.ncurc.js`)).
|
|
|
|
(Note that the test and coverage badges are generated automatically during
|
|
testing to ensure they are up to date, so you should not need to call those
|
|
scripts directly, and the license badges are updated before publishing.)
|
|
|
|
## Miscellaneous scripts
|
|
|
|
1. `npm run compress-images` - Compressing images is not part of other
|
|
preparation routines, as it is time-consuming and should not need
|
|
to be done frequently.
|
|
1. `npm run remark` - For linting Markdown. Not of high enough priority
|
|
currently to put into an automated routine.
|
|
1. `npm run lint` and `npm run eslint-fix` - For linting (or fixing)
|
|
linting errors. The non-fix version will be run automatically during
|
|
testing.
|
|
1. `npm run prep` - Run during `npm test` but may be useful to run
|
|
`npm run prep` as needed if normally testing through
|
|
`npm run test-only` which doesn't do the preparation. Composed of:
|
|
1. `npm run prep-no-core-rollup`
|
|
1. `npm run lint` (see above)
|
|
1. `npm run build-html` - Copies ESM HTML pages, replacing references
|
|
to ESM scripts to compiled/rolled up scripts.
|
|
1. `npm run build-by-config` - Runs the Rollup routines for
|
|
compiling just the ESM-based config files (since the user
|
|
config files are responsible for importing svgedit, one must
|
|
compile these to get a non-ESM build, but with the advantage
|
|
of avoiding globals and extra script tags).
|
|
1. `npm run rollup` - Runs the rollup routine for compiling the ESM-based
|
|
svgedit source files.
|
|
|
|
## Opening SVG editor from command line
|
|
|
|
It can be helpful to experiment with an editor by opening it from the command
|
|
line, even when automated tests already exist for a type of editor.
|
|
|
|
1. Opening the ESM editor with only the default extensions:
|
|
1. `npm run open` OR
|
|
1. `npm run open-no-start` if you already have a `start`
|
|
process running in another terminal tab.
|
|
1. Opening the ESM editor with all extensions (no automated tests currently):
|
|
1. `npm run open-all-ext` OR
|
|
1. `npm run open-all-ext-no-start` if you already have a `start`
|
|
process running in another terminal tab.
|
|
1. Opening an embedded (ESM) editor (no automated tests currently) (Note
|
|
that there is currently no build process for creating a non-ESM
|
|
embedded editor).
|
|
1. `npm run open-embedded` (This runs the normal `start` and also
|
|
`start-allow-origin` for running a separate server on a different
|
|
origin (a different port) so the embedded API can be tested
|
|
across origins.) OR
|
|
1. `npm run open-embedded-no-start` if you already have a `start`
|
|
process running in another terminal tab.
|
|
1. Opening an editor which is already pre-compiled (rolled up) and safe
|
|
for older non-ESM browsers (or for better performance in ESM browsers
|
|
as well, due to its use of fewer HTTP requests). This is the version
|
|
most likely to be used in production environments. However, this is
|
|
less convenient during normal debugging, as it requires that the
|
|
lengthier `prep` script be run first (these scripts do not do so
|
|
for you in case you are directly working on the compiled files,
|
|
though this is not recommended).
|
|
1. `npm run open-compiled` OR
|
|
1. `npm run open-compiled-no-start` if you already have a `start`
|
|
process running in another terminal tab.
|
|
|
|
## Reading/Opening test coverage reports
|
|
|
|
For testing coverage reports (see "Testing and coverage"), you can open
|
|
the HTML-based reports that are generated during the testing process (or
|
|
when running `npm run instrument` directly) from the command line into your
|
|
browser by the following commands:
|
|
|
|
1. Reading reports from the command line
|
|
1. `npm run report` (with some line numbers but not all lines as
|
|
with the HTML report) OR
|
|
1. `npm run report-summary` (no line numbers--only a summary)
|
|
1. Opening HTML-based test coverage report (indicating coverage status
|
|
for all lines)
|
|
1. `npm run open-cov` OR
|
|
1. `npm run open-cov-no-start` if you already have a `start`
|
|
process running in another terminal tab.
|
|
|
|
## Testing and coverage
|
|
|
|
For ensuring tests are passing and checking coverage.
|
|
|
|
You will most likely just need to use one of these three top-level
|
|
routines along with `npm run test-only`, but the other components are explained
|
|
here for reference. The most useful for regular development testing will probably
|
|
be `npm run open-tests`.
|
|
|
|
Note that you can configure Cypress through [its environmental variables](https://docs.cypress.io/guides/guides/environment-variables.html#Setting).
|
|
We recommend [this approach](https://docs.cypress.io/guides/guides/environment-variables.html#Option-2-cypress-env-json)
|
|
of adding to your own `cypress.env.json` at project root. You can set
|
|
your own [configuration options](https://docs.cypress.io/guides/references/configuration.html#Options).
|
|
Of particular interest may be setting `"video": false` if you wish to speed
|
|
up the tests and are not concerned with being able to check this after
|
|
running the headless tests (or during the running of headed tests in the
|
|
case of `open-tests`/`cypress:open`).
|
|
|
|
1. `npm test`. Headless testing comprised of:
|
|
1. `npm run instrument` - You can call this alone if you don't
|
|
actually wish to test but wish to get the files instrumented.
|
|
Should normally not be needed alone.
|
|
1. `npm run test-no-cov` - You can run this alone if you have already
|
|
run `npm run instrument` upon making changes. Should normally
|
|
not be run alone.
|
|
1. `npm run prep` (see above)
|
|
1. `npm run test-only` - This may be useful if you've instrumented and
|
|
run preparation steps after any code modifications, but just
|
|
need to re-run tests (e.g., if one did not complete them for
|
|
some reason). Also should be useful if tests are only against
|
|
the ESM builds (as is currently the case), and you therefore
|
|
don't need `prep` (and you are not concerned at the moment with
|
|
accurate coverage, so you can skip `instrument`). This script
|
|
includes a separate `report` step or otherwise the tests will
|
|
not show the results visibly on the command line. See also
|
|
`test-no-cov-no-core-rollup`.
|
|
1. `npm run test-only-no-report` - Should not be needed alone.
|
|
1. `npm start` - Starts the server
|
|
1. `npm run cypress:run` - Runs Cypress tests (`cypress run`).
|
|
`cypress:run` is made of subroutines which also merge
|
|
Mocha results (since Cypress produces separate files)
|
|
and updates the testing and coverage badges.
|
|
1. `npm run report` (see above)
|
|
1. `npm run test-no-core-rollup` - This applies the same headless testing
|
|
steps as `npm test` minus the time-consuming `npm run rollup`. This
|
|
script may be useful if you are only modifying config files but not
|
|
svgedit core.
|
|
1. `instrument` (see above)
|
|
1. `npm run test-no-cov-no-core-rollup`. As with `test-no-cov` but no
|
|
`npm run rollup` routine (part of `prep`).
|
|
1. `open-tests`
|
|
1. `instrument` (see above)
|
|
1. `cypress:open` - Useful without `instrument` if you are not concerned
|
|
at the moment with coverage. Note that the hot-reloading does not
|
|
currently reinstrument even if you ran through `open-tests`.
|
|
1. `npm start`
|
|
1. `cypress:open-no-start`. Runs `cypress open`, the headed mode. Useful
|
|
for testing single files with hot reloading.
|