Skip to content

Commit

Permalink
doc(book): remove implemented ideas
Browse files Browse the repository at this point in the history
Remove the sections from the ideas sections that have already been
implemented recently.
  • Loading branch information
dnaka91 committed Jan 19, 2024
1 parent 8dcf23b commit d8b987f
Showing 1 changed file with 0 additions and 14 deletions.
14 changes: 0 additions & 14 deletions book/src/ideas.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,6 @@

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.
Expand All @@ -21,11 +15,3 @@ Something that is missing from crates.io is to allow for private registries that
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.

## Schema evolution

When decoding a value, it may contain new fields and enum variants that are not known to the decoder yet. This can happen if the schema changed and but was only updated in one of two parties. For example a server might have introduced new fields to a response, but not all clients have updated to the new schema yet.

The same can happen the other way around. For example, if the data was saved in some form of storage and the schema evolved in the meantime, the decoder might encounter old data that lacks the newer content.

In both cases, the schema must be able to handle missing or unknown fields. Several rules must be upheld when updating a schema, to ensure it is both forward and backward compatible.

0 comments on commit d8b987f

Please sign in to comment.