From c8ea27ae2db47f7d56cd6174a8b86a91d1f86c67 Mon Sep 17 00:00:00 2001 From: jabba-jedi Date: Wed, 10 Jun 2020 19:34:03 +0300 Subject: [PATCH 1/2] Update doc-plan.md --- docs/doc-plan.md | 87 ++++++++++++++++-------------------------------- 1 file changed, 28 insertions(+), 59 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index 9492a59..df663db 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -1,58 +1,28 @@ -# SigTest Documentation plan - -- [SigTest Documentation plan](#sigtest-documentation-plan) - - [Overview aka What is it and what's it for](#overview-aka-what-is-it-and-whats-it-for) - - [Library features](#library-features) - - [You can need it when you](#you-can-need-it-when-you) - - [What it doesn't do](#what-it-doesnt-do) - - [Configuration](#configuration) - - [Configure Service Provided Interface (SPI) parameters](#configure-service-provided-interface-spi-parameters) - - [Configure members to ignore](#configure-members-to-ignore) - - [Global config](#global-config) - - [comparators](#comparators) - - [pathIgnorePatterns](#pathignorepatterns) - - [reportOutputDir](#reportoutputdir) - - [reportGenerator](#reportgenerator) - - [Usage](#usage) - - [Reference aka How it works](#reference-aka-how-it-works) - - [Testing flow](#testing-flow) - - [Supported members](#supported-members) - - [Comparators](#comparators-1) - - [Error codes](#error-codes) - -## Overview aka What is it and what's it for - -This library can compare TypeScript npm package exported file members for broke backwards compatibility. -Also it can generate reports (changelogs) and generate migration scripts (not all cases) -when code changes braked backwards compatibility. - -### Library features - -- check TypeScript code for backwards compatibility -- generate changelog -- provide migration scripts - -### You can need it when you - -- care about npm module backwards compatibility. -- want to test your library and know what version to bump patch or minor. -- want to have generated changelog in each version change. +## Overview aka What this lib does + +This library is excellent for: +comparing TypeScript npm package exported file members for broken backward compatibility. +generating reports (changelogs) +producing migration scripts (certain cases) for when the code changes break backward compatibility. + +### Why you need it +This lib is useful if you: +- care about npm module backward compatibility. +- want to test your library and know what version to bump: patch or minor. +- keep an auto-generated changelog for each release. ### What it doesn't do -- is not test tool/framework -- is not documentation generation tool +SigTest is not a test tool/framework, nor is it a documentation generation tool. ## Configuration ### Configure Service Provided Interface (SPI) parameters -SPI parameters have different compatibility requirements, than other data. -If SPI parameter has new property in it, this is not breaking change, -because nobody was using this property before and user is not implementing the -interface for the spi parameter. +SPI parameters have compatibility requirements that are different from the other data. +If the SPI parameter has a new property, this is not considered a breaking change, because nobody was using that property before, and the user is not implementing the interface for the SPI parameter. -Behavior, when SPI parameter is ignoring add _comparators_ can be configured using JsDocs [@callback](https://jsdoc.app/tags-callback.html) annotation in documentation block. Putting this annotation on the callback function will mark all parameter types as SPI parameters and will update _change_ from _breaking_ to _compatible_. +You can configure the SPI parameter behavior so that it ignores the add _comparators_. To set it like that, use the JsDocs [@callback](https://jsdoc.app/tags-callback.html) annotation in the documentation block. Put the @callback annotation on the callback function to mark all parameter types as SPI parameters and update the _change_ level from _breaking_ to _compatible_. _example_ @@ -71,7 +41,7 @@ interface ServiceProvidedInterface { ### Configure members to ignore -_Members_ in codebase can be explicitly ignored. Ignored _members_ will be ignored for all application life cycle. _Snapshots_ will not contain info about ignored members. Ignore behavior is configured with JsDoc [@ignore](https://jsdoc.app/tags-ignore.html) annotation in documentation block on the _member_ or its property. +You can configure SigTest to ignore _members_ in codebase explicitly. Ignored _members_ are ignored for the whole application lifecycle. _Snapshots_ won't contain info about the ignored members. Ignore behavior is configured with the JsDoc [@ignore](https://jsdoc.app/tags-ignore.html) annotation in the documentation block of the _member_ or its property. _example_ @@ -97,11 +67,11 @@ interface ServiceB { ### Global config -Global configuration is defined in the root of the project in `.config` file. +Define the global configuration in the root of the project in the `.config` file. -#### comparators +#### Comparators -_Comparators_ compatibility status can be redefined, or _comparator_ can be ignored at all. If _comparator_ compatibility status is redefined, the report still will be generated, if it is ignored, it will not be included in application life cycle. Here is a full list of [comparators](./comparators-table.md). +You can redefine the _comparators_ compatibility status, or ignore a _comparator_ can completely. If you redefine the _comparator_ compatibility status, the report is still generated; if you ignore the comparator, it is not included in the application lifecycle. See a full list of [comparators](./comparators-table.md) for more information. > type: `{ [comparator_name] : 'compatible'|'breaking'|'ignore' }` @@ -118,8 +88,8 @@ module.exports = { #### pathIgnorePatterns -Module path ignore patterns are defined under name `pathIgnorePatterns`. -Default value is `['node_modules']` +Define the module path ignore patterns under the `pathIgnorePatterns` name. +The default value is `['node_modules']` > type: `array` @@ -157,12 +127,12 @@ module.exports = { ## Usage -## Reference aka How it works +## SigTest workflow -Application will evaluate the following steps: +The application evaluates libraries with the following steps: - Generate snapshot (introspection) -- Load previous version snapshot +- Load the previous version snapshot - Process snapshots - Process changes - update changes @@ -220,11 +190,10 @@ The diagram goes here. ### Comparators -Comparators will compare members from previous version against current version. +Comparators compare the members from the previous version against the current version. The full list of comparators with description and examples -can be found here: [comparators definitions](./comparators-table.md). +is available here: [comparators definitions](./comparators-table.md). ### Error codes -Errors can occur during code introspection. -Error codes and definitions can be found [here](./error-code-table.md). +Errors can happen during code introspection. See the full list of error codes and definitions [here](./error-code-table.md). From 3e6618737c843c32573e4185a710d30d812d3960 Mon Sep 17 00:00:00 2001 From: jabba-jedi Date: Wed, 10 Jun 2020 19:41:19 +0300 Subject: [PATCH 2/2] Update doc-plan.md --- docs/doc-plan.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index df663db..8206cf5 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -1,3 +1,24 @@ +# SigTest Documentation plan + +- [SigTest Documentation plan](#sigtest-documentation-plan) + - [Overview aka What this lib does](#overview-aka-what-this-lib-does) + - [Why you need it](#why-you-need-it) + - [What it doesn't do](#what-it-doesnt-do) + - [Configuration](#configuration) + - [Configure Service Provided Interface (SPI) parameters](#configure-service-provided-interface-spi-parameters) + - [Configure members to ignore](#configure-members-to-ignore) + - [Global config](#global-config) + - [comparators](#comparators) + - [pathIgnorePatterns](#pathignorepatterns) + - [reportOutputDir](#reportoutputdir) + - [reportGenerator](#reportgenerator) + - [Usage](#usage) + - [Reference aka How it works](#reference-aka-how-it-works) + - [Testing flow](#testing-flow) + - [Supported members](#supported-members) + - [Comparators](#comparators-1) + - [Error codes](#error-codes) + ## Overview aka What this lib does This library is excellent for: