- Linting: Lint hidden ncurc.js file
- Docs: Add 6.0.0.md migration file - Docs: Update Contributing, Testing (renamed to Development), Linting and ReleaseInstructions - Docs: Info on submodules - npm: Add scripts for updating submodules - npm: Add `license-badges`, `build-docs`, and `copy` scripts to `prepublishOnly` script - npm: Bump to 6.0.0
This commit is contained in:
Brett Zamir
200
docs/Development.md
Normal file
200
docs/Development.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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 eslint` 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 eslint` (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.
|
||||
Reference in New Issue
Block a user