From bbdc49023e6f3121d6498bc1043bcbd05c06229c Mon Sep 17 00:00:00 2001 From: Dominik Nakamura Date: Fri, 27 Oct 2023 14:20:20 +0900 Subject: [PATCH] doc: add a few (far) future ideas Outline a few ideas that would be great to have in the future, but require a significant amount of work. Therefore, these have no time frame attached to them. --- book/src/SUMMARY.md | 1 + book/src/ideas.md | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 book/src/ideas.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index fb2b807..1e6252f 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -5,6 +5,7 @@ [Introduction](introduction.md) [General idea](general_idea.md) +[Ideas](ideas.md) --- diff --git a/book/src/ideas.md b/book/src/ideas.md new file mode 100644 index 0000000..1f8d4fc --- /dev/null +++ b/book/src/ideas.md @@ -0,0 +1,23 @@ +# Ideas + +The following are general ideas for this project, that are not yet implemented or even close to being developed, but definitely on the list of ideas for the future. + +## Documentation generator + +Similar to Rust's [rustdoc](https://doc.rust-lang.org/rustdoc/index.html), it would be nice to have a documentation generator built in. The doc comments can be extended to be parsed as Markdown and allow for rich formatting in the docs. + +As a nice side effect, if parsing the comments as Markdown upfront it can be used to transform the docs into native documentation where Markdown is not supported (for example JavaDoc in Java/Kotlin projects). + +## Central registry for schemas + +Rust has [crates.io](https://crates.io) as central repository for sharing libraries. In similar fashion, a registry for schema files could be created. It would allow easy sharing of schemas. + +This should be kept simple and then extended further as features are needed. + +Something that is missing from crates.io is to allow for private registries that can be self-hosted, while still being able to get schemas from the main repository (like a proxy, preferring local packages but pulling and caching any schemas that are not present locally). + +## Breaking change detection + +The schema allows for certain changes that are backwards compatible and do not create a break in the wire format. That means older generated code is still able to read the data despite being created by a newer version of the schema. But the rules are difficult to always keep in mind and mistakes can easily be made. + +To avoid accidental breaking changes, it would be nice to have an auto-detection mechanism that compares the current version to a previous one whenever changes are made. The _old_ version could be the current Git HEAD compared to the local changes.