Publish doca roadmap (with requirements)

[handrews]

We are currently collecting requirements internally and via issues here for doca, and will be putting together a loose road map for the project. We should publish some form of that on the wiki here for community feedback and input. I'm filing this mostly to let people know it's a thing :-)

Of the top of my head, without factoring the requirements-gathering that's just started, I expect something along the lines of:

• 0.x releases will be strictly compatible, but not a long-term support (LTS) release line
  • We will do a bit more with this to fix easy but important issues
  • No guarantees at this time that any specific thing will be fixed in 0.x
• 1.0 release will involve minor breakage, easy migration, and 1.x will be an LTS release line
  • Need to define what LTS means for doca
  • Within the 1.x line, we will maintain compatibility
  • We will need this to continue to document Cloudflare's v4 APIs
  • Other JSON-base HTTP APIs that are not strictly RESTful can depend on this
  • Hopefully we can automate the schema edits needed for migration
  • 1.x will probably not support JSON Schema drafts after Draft 04, unless someone wants to take that on and write PRs for it
  • Fixing the nonstandard usage of "rel": "self" is the kind of breaking change compared to 0.x that we'll do here
  • Issues like #10 (standards-compliant URI Template variables) need more work on the JSON Schema spec side, and will likely not be addressed in 1.x
• 2.0 release will be based on JSON Schema Draft 06 and will be more hypermedia-oriented
  • Hopefully this will also drive ideas for a JSON Documentation Schema specification (json-schema-org/json-schema-spec#136)
  • Migrating from 1.x to 2.x will likely require manual changes to schemas
  • Priority will be given to fully RESTful APIs (strict compliance with HTTP semantics, etc.)
  • Supporting other API approaches may depend on community contributions
  • This will probably be an experimental release line, which when stable can cut over to a 3.0 LTS release line

Take all of the above with a grain of salt, as I literally made it up while typing without consulting anyone else.

If you have specific asks for future releases, please file them as their own issues. If you have more general comments, questions, or concerns, please comment here. When we publish the road map on the wiki I'll ensure everything is addressed in some way and close this issue.

[handrews]

Paging @Relequestual, @habitullence, and (because we're likely to move to Ajv instead of the existing 3rd-party parser library to fix #11, get Draft 06 support, and other reasons) @epoberezkin

[Relequestual]

Looks like the start of a plan! Great stuff. You already have my feedback prior to properly using it. Pretty much the same. Still getting the hang of node and webpack... =]

[handrews]

Getting back to this now and working on improving compliance with draft-04.

[handrews]

I've organized as many of the issues as possible into three milestones, which I'll be working on in roughly the following order:

• Draft-04 Conformance
• Build/Run/Test
• API Docs vocabulary
• Draft-06 Conformance

I may split Draft-04 Conformance into two milestones: essential support (including documenting what is not supported) and full support (for things that we can't justify supporting right now, and may never be able to justify now that Draft-06 is out). For now I'm keeping it all together in hopes that we can support everything that is at all reasonable to consider.

I've also labeled the issues by which part of the suite needs work to implement them, which should make the project a bit more approachable for any potential contributors.

[handrews]

Split a few things out of draft-04 conformance to track the things that are actually broken separately from the things that are just not implemented:

Draft-04 no contradctions

[Relequestual]

Great organisational work!

I probably need to modify our use of doca to make sure we're using a fixed version in production, so we can test changes in develop.

I believe doca currently doesn't specify specific versions of the theme or example loader. I wonder if it should to avoid the situation where an older release of doca no longer works because newer versions of dependancies are not backwards compatible with doca?

Great stuff!

[handrews]

PR #72 proposes a substantial refactoring of the doca suite that will produce a more flexible, extensible, and maintainable architecture (and modernize a few things along the way, since even though doca proper is less than a year old, the loader code is older than that and JS technologies change every year or two anyway).

The most significant reason for the change is that the majority of requested improvements require work on the theme, and currently that work ends up duplicated between the public and internal themes. We will merge the React components into one UI and handle theming at the CSS / static asset level.

There are a number of other refactorings planned to modularize the schema transformations in the loaders and ensure that at every step, including the final loader output, the result is still a valid, standards-compliant JSON Schema.

I'll leave the PR open for a few days for feedback, and then unless there are objections I will merge it and close this. It will be a few weeks before I start on the road map tasks in earnest, so there will be additional time to raise concerns and make changes.

[handrews]

Road map published.

For further discussion, file new issues and reference https://github.com/cloudflare/doca/blob/master/ROADMAP.md