-
Notifications
You must be signed in to change notification settings - Fork 24.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added migration/index.asciidoc generation support (#87318)
Including extracting static content from migration/index, so the template would be as light as possible. The reason for this work is because the gradle task `generateReleaseNotes` was not correctly adding new links and imports to the migrations/index and that caused documentation to fail building for 8.3.0.
- Loading branch information
1 parent
8f31c02
commit a4e0d9b
Showing
8 changed files
with
196 additions
and
31 deletions.
There are no files selected for viewing
This file contains 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
50 changes: 50 additions & 0 deletions
50
...rnal/src/main/java/org/elasticsearch/gradle/internal/release/MigrationIndexGenerator.java
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| /* | ||
| * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one | ||
| * or more contributor license agreements. Licensed under the Elastic License | ||
| * 2.0 and the Server Side Public License, v 1; you may not use this file except | ||
| * in compliance with, at your election, the Elastic License 2.0 or the Server | ||
| * Side Public License, v 1. | ||
| */ | ||
|
|
||
| package org.elasticsearch.gradle.internal.release; | ||
|
|
||
| import com.google.common.annotations.VisibleForTesting; | ||
|
|
||
| import java.io.File; | ||
| import java.io.FileWriter; | ||
| import java.io.IOException; | ||
| import java.nio.file.Files; | ||
| import java.util.HashMap; | ||
| import java.util.List; | ||
| import java.util.Map; | ||
| import java.util.Set; | ||
| import java.util.TreeSet; | ||
| import java.util.stream.Collectors; | ||
|
|
||
| import static java.util.Comparator.reverseOrder; | ||
|
|
||
| /** | ||
| * This class ensures that the migrate/index page has the appropriate anchors and include directives | ||
| * for the current repository version. | ||
| */ | ||
| public class MigrationIndexGenerator { | ||
|
|
||
| static void update(Set<MinorVersion> versions, File indexTemplate, File indexFile) throws IOException { | ||
| try (FileWriter indexFileWriter = new FileWriter(indexFile)) { | ||
| indexFileWriter.write(generateFile(versions, Files.readString(indexTemplate.toPath()))); | ||
| } | ||
| } | ||
|
|
||
| @VisibleForTesting | ||
| static String generateFile(Set<MinorVersion> versionsSet, String template) throws IOException { | ||
| final Set<MinorVersion> versions = new TreeSet<>(reverseOrder()); | ||
| versions.addAll(versionsSet); | ||
| final List<String> includeVersions = versions.stream().map(MinorVersion::underscore).collect(Collectors.toList()); | ||
|
|
||
| final Map<String, Object> bindings = new HashMap<>(); | ||
| bindings.put("versions", versions); | ||
| bindings.put("includeVersions", includeVersions); | ||
|
|
||
| return TemplateUtils.render(template, bindings); | ||
| } | ||
| } |
47 changes: 47 additions & 0 deletions
47
...-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/MinorVersion.java
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| /* | ||
| * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one | ||
| * or more contributor license agreements. Licensed under the Elastic License | ||
| * 2.0 and the Server Side Public License, v 1; you may not use this file except | ||
| * in compliance with, at your election, the Elastic License 2.0 or the Server | ||
| * Side Public License, v 1. | ||
| */ | ||
|
|
||
| package org.elasticsearch.gradle.internal.release; | ||
|
|
||
| import java.util.Comparator; | ||
| import java.util.Objects; | ||
|
|
||
| /** | ||
| * Encapsulates comparison and printing logic for an x.y. | ||
| */ | ||
| public record MinorVersion(int major, int minor) implements Comparable<MinorVersion> { | ||
| /** | ||
| * Converts a QualifiedVersion into a MinorVersion by deleting all but the major and minor components. | ||
| */ | ||
| public static MinorVersion of(final QualifiedVersion v) { | ||
| Objects.requireNonNull(v); | ||
| return new MinorVersion(v.major(), v.minor()); | ||
| } | ||
|
|
||
| @Override | ||
| public String toString() { | ||
| return major + "." + minor; | ||
| } | ||
|
|
||
| /** Generate version string with underscore instead of dot */ | ||
| public String underscore() { | ||
| return major + "_" + minor; | ||
| } | ||
|
|
||
| private static final Comparator<MinorVersion> COMPARATOR = Comparator.comparing((MinorVersion v) -> v.major) | ||
| .thenComparing(v -> v.minor); | ||
|
|
||
| @Override | ||
| public int compareTo(MinorVersion other) { | ||
| return COMPARATOR.compare(this, other); | ||
| } | ||
|
|
||
| public boolean isBefore(MinorVersion other) { | ||
| return this.compareTo(other) < 0; | ||
| } | ||
| } |
This file contains 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
4 changes: 4 additions & 0 deletions
4
build-tools-internal/src/main/resources/templates/migration-index.asciidoc
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| include::migration_intro.asciidoc[] | ||
|
|
||
| <% versions.each { print "* <<migrating-${ it },Migrating to ${ it }>>\n" } %> | ||
| <% includeVersions.each { print "include::migrate_${ it }.asciidoc[]\n" } %> |
This file contains 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 file contains 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 file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| [[breaking-changes]] | ||
| = Migration guide | ||
|
|
||
| This section discusses the changes that you need to be aware of to migrate | ||
| your application to {version}. For more information about what's new in this | ||
| release, see the <<release-highlights>> and <<es-release-notes>>. | ||
|
|
||
| As {es} introduces new features and improves existing ones, the changes | ||
| sometimes make older settings, APIs, and parameters obsolete. We typically | ||
| deprecate obsolete functionality as part of a release. If possible, we support | ||
| the deprecated functionality for several subsequent releases before removing it. | ||
| This enables applications to continue working unchanged while you prepare to | ||
| migrate away from the deprecated functionality. | ||
|
|
||
| To get the most out of {es} and facilitate future upgrades, we strongly | ||
| encourage migrating away from using deprecated functionality as soon as | ||
| possible. | ||
|
|
||
| To give you insight into what deprecated features you're using, {es}: | ||
|
|
||
| - Returns a `Warn` HTTP header whenever you | ||
| submit a request that uses deprecated functionality. | ||
| - <<deprecation-logging, Logs deprecation warnings>> when | ||
| deprecated functionality is used. | ||
| - <<migration-api-deprecation, Provides a deprecation info API>> | ||
| that scans a cluster's configuration | ||
| and mappings for deprecated functionality. | ||
|
|
||
| For more information about {minor-version}, | ||
| see the <<release-highlights>> and <<es-release-notes>>. | ||
| For information about how to upgrade your cluster, see <<setup-upgrade>>. |