-
Notifications
You must be signed in to change notification settings - Fork 36
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #86 from handrews/roadmap
Update ROADMAP to point to new repo
- Loading branch information
Showing
1 changed file
with
27 additions
and
164 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,166 +1,29 @@ | ||
| # Doca Suite Road Map | ||
|
|
||
| ## Overview | ||
|
|
||
| We are about to embark on a major refactoring and update to the Doca suite with two main goals: | ||
|
|
||
| 1. Make it easier to maintain and extend | ||
| * More fine-grained loader steps | ||
| * Unified shared UI package to avoid duplicate work | ||
| * Themes supported at the CSS / static assets level | ||
| 2. Comply with JSON Hyper-Schema drafts | ||
| * Support draft-04 as fully as possible | ||
| * Make it easy to add draft-06 support ASAP | ||
|
|
||
|
|
||
| ### Current suite architecture | ||
|
|
||
| There are curently four components to the doca suite: | ||
|
|
||
| * doca | ||
| * CLI tool to generate an app for a specific API | ||
| * Copies package.json and json-schema-example-loader config.js | ||
| * Populates schema.js with supplied schemas | ||
| * Configures the theme | ||
| * Provides entry point React component | ||
| * Sets up Webpack development and production builds | ||
| * Connects the various components into an app | ||
| * json-schema-loader (JSL) | ||
| * tracks dependencies among schemas | ||
| * statically resolves references | ||
| * circular references not supported due to serialization issues | ||
| * passes a JavaScript object in a mechanism dropped in the final Webpack 2 release | ||
| * json-schema-example-loader (JSEL) | ||
| * operates on the JS object from JSL | ||
| * mainupulates some schema keywords, passes others through | ||
| * rolls up examples from scalars to objects and arrays | ||
| * produces a non-schema JSON string as output | ||
| * lots of unit tests (> 90% coverage) | ||
| * doca-\*-theme | ||
| * takes JSEL output as its input | ||
| * provides all React components except the entry point | ||
| * provides all UI layout and interactive functionality | ||
| * provides all styling and static assets | ||
|
|
||
| ### Advantages of current architecture | ||
|
|
||
| * Processing JSON in Webpack loaders is the right approach | ||
| * Flexibility in the app front-end is an advantage | ||
| * Scaffolding approach is good | ||
|
|
||
| ### Issues with current architecture | ||
|
|
||
| * general technology choices at Cloudflare | ||
| * we now use ES6 and Seamless-Immutable, not Lodash | ||
| * we now use Seamless-Immutable, not ImmutableJS | ||
| * Webpack 2 is now finalized, and changed from beta | ||
| * we now use jest instead of mocha for unit testing | ||
| * we are trying out Fela to manage CSS in JS | ||
| * we now use Prettier for auto-formatting | ||
| * we may want to use Lerna to manage a doca mono-repo | ||
| * doca-\*-theme | ||
| * doca-\*-theme does nearly all front-end work | ||
| * to keep feature parity, all front-end work needs to be replicated to each theme | ||
| * most customizations are visual rather than functional | ||
| * json-schema-example-loader | ||
| * not entirely compliant with JSON Schema draft-04 | ||
| * lots of special casing of keywords and keyword combinations | ||
| * some parallel special casing in multiple places | ||
| * example transformations not applied uniformly | ||
| * cannot handle circular references | ||
| * json-schema-loader | ||
| * relies on a feature removed in Webpack 2 | ||
| * dereference + stringify prevents circular refs from working | ||
| * doca | ||
| * no clear place for app-specific content (pushes it to the theme) | ||
| * no way to safely regenerate while preserving customizations *(but do we have use cases for this?)* | ||
|
|
||
| ## Architectural goals | ||
|
|
||
| The broad strokes of the Doca suite's architecture will be retained: | ||
|
|
||
| * The `doca` CLI tool will scaffold a React app for the specific API | ||
| * Webpack 2 loaders modify the schema to be more suitable for doc generation | ||
| * A shared React package will provide most of the front-end functionality | ||
|
|
||
| However, we want to make some tweaks to the specifics: | ||
|
|
||
| * The output of each loader in the pipeline will still be a valid draft-04 schema | ||
| * Extension keywords used by doca or generated by the loaders will use a prefix or wrapping object to avoid collisions and make the output more easily understood | ||
| * The current "theme" idea will be split into a single shared React package that supports CSS themes through Fela | ||
| * There will be a mechanism to make it easier to add introductory material and other more free-form content | ||
|
|
||
| ### Proposed architecture | ||
|
|
||
| In addition to migrating to our current technology ecosystem, the packages will be refactored and (where possible) simplified. The webpack loader pipeline will be longer, following the guideline that [each loader should only do one thing](https://webpack.js.org/development/how-to-write-a-loader/#guidelines). | ||
|
|
||
| * doca | ||
| * scaffolds very much like the current system | ||
| * sets up webpack builds | ||
| * provides app entry point | ||
| * provides clear places for custom content | ||
| * can safely update scaffolding *(if we have use cases)* | ||
| * json-schema-loader (JSL) | ||
| * tracks depenencies | ||
| * can find .json or .yaml dependencies if URLs have no extension | ||
| * options to either bundles and minimizes references... | ||
| * ...or fully dereferences (only works with no circular refs) | ||
| * json-schema-flattening-loader (JSFL) | ||
| * output is valid JSON Schema, validating the same instance set | ||
| * not all keyword combinations can be flattened | ||
| * extensions (input and output) clearly namespaced | ||
| * Simplifies the combinatoric kewyords | ||
| * merge `"allOf"`s together and into containing schema | ||
| * distribute containing schema across `"anyOf"` | ||
| * optionally distribute over `"oneOf"` into extension output (this likely changes the validating set) | ||
| * flattens across non-circular `"$ref"`s (unless told not to) | ||
| * circular references remain `"$ref"` | ||
| * supports a `"jsfl-doNotFlatten"` extension keyword | ||
| * containing annotation keywords overwrite contained ones | ||
| * *if no containing annotation, use the first available?* | ||
| * *what to do with `"*Of"` branch `"examples"`?* | ||
| * json-schema-example-loader (JSEL) | ||
| * rolls up examples | ||
| * uses `"default"` if there are no `"examples"` | ||
| * an `"examples"` in an object/array preempts a roll-up of its members/elements' `"examples"` | ||
| * a `"default"` does not overwrite the roll-up | ||
| * provides a `"jsel-doNotRollUp"` extension keyword | ||
| * circular references supported | ||
| * extensions (input and output) clearly namespaced | ||
| * json-schema-apidoc-loader (JSAL) | ||
| * looks for links and generates request / response examples | ||
| * adds header and auth extensions to structural examples | ||
| * creates curl (and/or other) examples `"_jsel-curl"`, etc. | ||
| * builds link graph (not in MVP) for HATEOAS docs | ||
| * handles circular references | ||
| * doca-ui | ||
| * the React components from the themes | ||
| * uses Fela for CSS in JS | ||
| * can be replaced for custom UI, but probably rare | ||
| * fela themes | ||
| * customization for doca-components | ||
| * *static assets here, as custom content in scaffolded app, or a mix?* | ||
|
|
||
|
|
||
| #### Minimum viable product | ||
|
|
||
| The MVP must satisfy the following: | ||
|
|
||
| * Feature parity with the existing output format, minus non-compliant features | ||
| * All supported keywords will be draft-04 compliant | ||
| * Support `"$ref": "#"` wherever the nonstandard `"rel": "self"` was supported | ||
| * Other circular reference usage may not be supported in the MVP | ||
| * Keywords beyond current supported set may not all be supported | ||
| * Provide sensible errors when encountering known unsupported keywords | ||
| * Schema simplification through flattening | ||
| * Some keywords or combinations may not be supported for flattening | ||
| * Custom keywords will be namespaced in some way | ||
| * Examples for all entities and fields | ||
| * Object/array examples built up from field examples | ||
| * Use `"default"` if no `"examples"` present | ||
| * Use first entry in `"examples"` array | ||
| * Extension keyword for omitting properties from roll-up | ||
| * API usage documentation | ||
| * Extension keyword for setting and overriding headers | ||
| * Curl request examples will be generated, with headers | ||
| * Base URI with either draft-04's self links or draft-06's `"base"` | ||
| Phase One of the Doca Suite overhaul is complete! | ||
|
|
||
| The new back-end (and a bare-bones debugging front-end) for the doca suite | ||
| may be found at the [JSON Schema Tools](https://github.com/cloudflare/json-schema-tools) | ||
| monorepo. While not everything exactly aligns with the plan as sketched out here, the | ||
| basics were achieved: | ||
|
|
||
| * Tool packages for working with JSON Schemas in generic ways | ||
| * Libraries for applying schema transformations necessary for generating docs | ||
| * Transformed schemas ***are still schemas*** and can still be used with standard tools | ||
| * Technology choices and package versions have been updated where possible | ||
| (although it's a moving target) | ||
| * Webpack loaders do the absolute minimum work, deferring most code to the libraries | ||
| * Schemas can be read in more formats (JSON, JSON5, YAML, JavaScript) and referenced in | ||
| "id"/"$id" and "$ref" without the extension and still work. | ||
| * Basic groundwork laid to support multiple vocabularies from draft-04 to draft-07, | ||
| optionally including Cloudflare-specific extensions. A few peieces, most notably | ||
| the draft-06 "examples" (plural) keyword, still need work. | ||
|
|
||
| Some major limitations remain around circular references, but it should be easier to provide | ||
| options there going forward. | ||
|
|
||
| Please join further efforts at | ||
| [the new repository](https://github.com/cloudflare/json-schema-tools). | ||
|
|
||
| Any ideas from here that did not get picked up should be re-considered for the ROADMAP | ||
| to be built over there. |