Publish doca roadmap (with requirements)

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]

Road map published.

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

[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.