Introduce MIGRATION warnings #686
Merged
Conversation
This file contains hidden or 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
This adds the concept of "MIGRATION warnings" that are specifically around migrating to Asciidoctor. By default these warnings are only enforced against the "latest" version of each book where "latest" is the first version listed in the `branches` list. The idea is that we'd like "modern" versions of the documentation to be fully Asciioctor compatible but that we won't be able to do that overnight and that we won't be able to modify very old documentation to be compatible and we will forever rely on the compatibility layer in branches that are not actively being developed. This only adds a single `MIGRATION` warning, emitted when the start of a code block doesn't match the end of a code block. These are very simple to fix and we can fix them before migrating the book to Asciidoctor. In future work we'll want to emit `MIGRATION` warnings when we use the "old" style for things like the `beta[]` macro. Since the "new" style is not compatible with Asciidoc the order of operations has to be: 1. Switch the book to Asciidoctor, suppressing the warnings for `beta[]` 2. Migrate all usages of the `beta[]` macro to the new `beta::[]` style. 3. Remove the suppression. This change doesn't have a way to suppress any `MIGRATION` warnings on the latest version of the each book. As I said above, it *always* suppresses them on older versions. When you use `./build_docs --doc` we can't tell whether you are building the latest version of a book or an older version so we assume that you are building the latest version. This is the most common thing. When you build an older version you can do ``` ./build_docs --suppress_migration_warnings --doc foo.asciidoctor ``` to suppress the `MIGRATION` warnings. Begins work on elastic#671
|
Thanks for reviewing @Jarpy! |
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds the concept of "MIGRATION warnings" that are specifically
around migrating to Asciidoctor. By default these warnings are only
enforced against the "latest" version of each book where "latest" is the
first version listed in the
brancheslist. The idea is that we'd like"modern" versions of the documentation to be fully Asciioctor
compatible but that we won't be able to do that overnight and that we
won't be able to modify very old documentation to be compatible and we
will forever rely on the compatibility layer in branches that are not
actively being developed.
This only adds a single
MIGRATIONwarning, emitted when the start of acode block doesn't match the end of a code block. These are very simple
to fix and we can fix them before migrating the book to Asciidoctor.
In future work we'll want to emit
MIGRATIONwarnings when we use the"old" style for things like the
beta[]macro. Since the "new" styleis not compatible with Asciidoc the order of operations has to be:
beta[]beta[]macro to the newbeta::[]style.This change doesn't have a way to suppress any
MIGRATIONwarnings onthe latest version of the each book. As I said above, it always
suppresses them on older versions.
When you use
./build_docs --docwe can't tell whether you are buildingthe latest version of a book or an older version so we assume that you
are building the latest version. This is the most common thing. When you
build an older version you can do
to suppress the
MIGRATIONwarnings.Begins work on #671