Skip to content

Commit de7261d

Browse files
pugnascotiapugnascotia
authored
Use new changelog process in 7.17 (#85315)
Backport of #85279. * Split the 7.17 release notes into a page per patch version * Sync the release notes task code with master * Various adjustments to align the generated docs with the existing docs
1 parent 38b3bc4 commit de7261d

35 files changed

+734
-748
lines changed

‎build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/BreakingChangesGenerator.java‎

Lines changed: 29 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -21,51 +21,61 @@
2121
import java.util.Map;
2222
import java.util.Objects;
2323
import java.util.TreeMap;
24-
import java.util.stream.Collectors;
2524

2625
import static java.util.Comparator.comparing;
2726
import static java.util.stream.Collectors.groupingBy;
27+
import static java.util.stream.Collectors.toList;
2828

2929
/**
30-
* Generates the page that lists the breaking changes and deprecations for a minor version release.
30+
* Generates the page that contains breaking changes deprecations for a minor release series.
3131
*/
3232
public class BreakingChangesGenerator {
3333

34-
static void update(File templateFile, File outputFile, List<ChangelogEntry> entries) throws IOException {
35-
try (FileWriter output = new FileWriter(outputFile)) {
34+
static void update(File migrationTemplateFile, File migrationOutputFile, List<ChangelogEntry> entries) throws IOException {
35+
try (FileWriter output = new FileWriter(migrationOutputFile)) {
3636
output.write(
37-
generateFile(QualifiedVersion.of(VersionProperties.getElasticsearch()), Files.readString(templateFile.toPath()), entries)
37+
generateMigrationFile(
38+
QualifiedVersion.of(VersionProperties.getElasticsearch()),
39+
Files.readString(migrationTemplateFile.toPath()),
40+
entries
41+
)
3842
);
3943
}
4044
}
4145

4246
@VisibleForTesting
43-
static String generateFile(QualifiedVersion version, String template, List<ChangelogEntry> entries) throws IOException {
47+
static String generateMigrationFile(QualifiedVersion version, String template, List<ChangelogEntry> entries) throws IOException {
48+
final Map<Boolean, Map<String, List<ChangelogEntry.Deprecation>>> deprecationsByNotabilityByArea = entries.stream()
49+
.map(ChangelogEntry::getDeprecation)
50+
.filter(Objects::nonNull)
51+
.sorted(comparing(ChangelogEntry.Deprecation::getTitle))
52+
.collect(
53+
groupingBy(
54+
ChangelogEntry.Deprecation::isNotable,
55+
TreeMap::new,
56+
groupingBy(ChangelogEntry.Deprecation::getArea, TreeMap::new, toList())
57+
)
58+
);
4459

45-
final Map<Boolean, Map<String, List<ChangelogEntry.Breaking>>> breakingChangesByNotabilityByArea = entries.stream()
60+
final Map<Boolean, Map<String, List<ChangelogEntry.Breaking>>> breakingByNotabilityByArea = entries.stream()
4661
.map(ChangelogEntry::getBreaking)
4762
.filter(Objects::nonNull)
4863
.sorted(comparing(ChangelogEntry.Breaking::getTitle))
4964
.collect(
5065
groupingBy(
5166
ChangelogEntry.Breaking::isNotable,
52-
groupingBy(ChangelogEntry.Breaking::getArea, TreeMap::new, Collectors.toList())
67+
TreeMap::new,
68+
groupingBy(ChangelogEntry.Breaking::getArea, TreeMap::new, toList())
5369
)
5470
);
5571

56-
final Map<String, List<ChangelogEntry.Deprecation>> deprecationsByArea = entries.stream()
57-
.map(ChangelogEntry::getDeprecation)
58-
.filter(Objects::nonNull)
59-
.sorted(comparing(ChangelogEntry.Deprecation::getTitle))
60-
.collect(groupingBy(ChangelogEntry.Deprecation::getArea, TreeMap::new, Collectors.toList()));
61-
6272
final Map<String, Object> bindings = new HashMap<>();
63-
bindings.put("breakingChangesByNotabilityByArea", breakingChangesByNotabilityByArea);
64-
bindings.put("deprecationsByArea", deprecationsByArea);
73+
bindings.put("breakingByNotabilityByArea", breakingByNotabilityByArea);
74+
bindings.put("deprecationsByNotabilityByArea", deprecationsByNotabilityByArea);
6575
bindings.put("isElasticsearchSnapshot", version.isSnapshot());
66-
bindings.put("majorDotMinor", version.getMajor() + "." + version.getMinor());
67-
bindings.put("majorMinor", String.valueOf(version.getMajor()) + version.getMinor());
68-
bindings.put("nextMajor", (version.getMajor() + 1) + ".0");
76+
bindings.put("majorDotMinor", version.major() + "." + version.minor());
77+
bindings.put("majorMinor", String.valueOf(version.major()) + version.minor());
78+
bindings.put("nextMajor", (version.major() + 1) + ".0");
6979
bindings.put("version", version);
7080

7181
return TemplateUtils.render(template, bindings);

‎build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/ChangelogEntry.java‎

Lines changed: 33 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,11 @@ public class ChangelogEntry {
4040

4141
private static final ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory());
4242

43+
/**
44+
* Create a new instance by parsing the supplied file
45+
* @param file the YAML file to parse
46+
* @return a new instance
47+
*/
4348
public static ChangelogEntry parse(File file) {
4449
try {
4550
return yamlMapper.readValue(file, ChangelogEntry.class);
@@ -209,12 +214,17 @@ public String toString() {
209214
}
210215
}
211216

212-
public static class Breaking {
217+
public static class Breaking extends CompatibilityChange {}
218+
219+
public static class Deprecation extends CompatibilityChange {}
220+
221+
abstract static class CompatibilityChange {
213222
private String area;
214223
private String title;
215224
private String details;
216225
private String impact;
217226
private boolean notable;
227+
private boolean essSettingChange;
218228

219229
public String getArea() {
220230
return area;
@@ -260,6 +270,14 @@ public String getAnchor() {
260270
return generatedAnchor(this.title);
261271
}
262272

273+
public boolean isEssSettingChange() {
274+
return essSettingChange;
275+
}
276+
277+
public void setEssSettingChange(boolean essSettingChange) {
278+
this.essSettingChange = essSettingChange;
279+
}
280+
263281
@Override
264282
public boolean equals(Object o) {
265283
if (this == o) {
@@ -268,92 +286,40 @@ public boolean equals(Object o) {
268286
if (o == null || getClass() != o.getClass()) {
269287
return false;
270288
}
271-
Breaking breaking = (Breaking) o;
272-
return notable == breaking.notable
273-
&& Objects.equals(area, breaking.area)
274-
&& Objects.equals(title, breaking.title)
275-
&& Objects.equals(details, breaking.details)
276-
&& Objects.equals(impact, breaking.impact);
289+
CompatibilityChange breaking = (CompatibilityChange) o;
290+
return notable == breaking.isNotable()
291+
&& Objects.equals(area, breaking.getArea())
292+
&& Objects.equals(title, breaking.getTitle())
293+
&& Objects.equals(details, breaking.getDetails())
294+
&& Objects.equals(impact, breaking.getImpact())
295+
&& Objects.equals(essSettingChange, breaking.isEssSettingChange());
277296
}
278297

279298
@Override
280299
public int hashCode() {
281-
return Objects.hash(area, title, details, impact, notable);
300+
return Objects.hash(area, title, details, impact, notable, essSettingChange);
282301
}
283302

284303
@Override
285304
public String toString() {
286305
return String.format(
287-
"Breaking{area='%s', title='%s', details='%s', impact='%s', isNotable=%s}",
306+
"%s{area='%s', title='%s', details='%s', impact='%s', notable=%s, essSettingChange=%s}",
307+
this.getClass().getSimpleName(),
288308
area,
289309
title,
290310
details,
291311
impact,
292-
notable
312+
notable,
313+
essSettingChange
293314
);
294315
}
295316
}
296317

297-
public static class Deprecation {
298-
private String area;
299-
private String title;
300-
private String body;
301-
302-
public String getArea() {
303-
return area;
304-
}
305-
306-
public void setArea(String area) {
307-
this.area = area;
308-
}
309-
310-
public String getTitle() {
311-
return title;
312-
}
313-
314-
public void setTitle(String title) {
315-
this.title = title;
316-
}
317-
318-
public String getBody() {
319-
return body;
320-
}
321-
322-
public void setBody(String body) {
323-
this.body = body;
324-
}
325-
326-
public String getAnchor() {
327-
return generatedAnchor(this.title);
328-
}
329-
330-
@Override
331-
public boolean equals(Object o) {
332-
if (this == o) {
333-
return true;
334-
}
335-
if (o == null || getClass() != o.getClass()) {
336-
return false;
337-
}
338-
Deprecation that = (Deprecation) o;
339-
return Objects.equals(area, that.area) && Objects.equals(title, that.title) && Objects.equals(body, that.body);
340-
}
341-
342-
@Override
343-
public int hashCode() {
344-
return Objects.hash(area, title, body);
345-
}
346-
347-
@Override
348-
public String toString() {
349-
return String.format("Deprecation{area='%s', title='%s', body='%s'}", area, title, body);
350-
}
351-
}
352-
353318
private static String generatedAnchor(String input) {
354-
final List<String> excludes = List.of("the", "is", "a");
319+
final List<String> excludes = List.of("the", "is", "a", "and", "now", "that");
355320

356321
final String[] words = input.toLowerCase(Locale.ROOT)
322+
.replaceAll("'", "")
357323
.replaceAll("[^\\w]+", "_")
358324
.replaceFirst("^_+", "")
359325
.replaceFirst("_+$", "")

‎build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/release/GenerateReleaseNotesTask.java‎

Lines changed: 25 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,13 @@
3434
import java.util.HashSet;
3535
import java.util.Iterator;
3636
import java.util.List;
37+
import java.util.Locale;
3738
import java.util.Map;
3839
import java.util.Set;
3940

4041
import javax.inject.Inject;
4142

4243
import static java.util.Comparator.naturalOrder;
43-
import static java.util.stream.Collectors.toList;
4444
import static java.util.stream.Collectors.toSet;
4545

4646
/**
@@ -59,7 +59,7 @@ public class GenerateReleaseNotesTask extends DefaultTask {
5959
private final RegularFileProperty releaseNotesIndexFile;
6060
private final RegularFileProperty releaseNotesFile;
6161
private final RegularFileProperty releaseHighlightsFile;
62-
private final RegularFileProperty breakingChangesFile;
62+
private final RegularFileProperty breakingChangesMigrationFile;
6363

6464
private final GitWrapper gitWrapper;
6565

@@ -75,22 +75,24 @@ public GenerateReleaseNotesTask(ObjectFactory objectFactory, ExecOperations exec
7575
releaseNotesIndexFile = objectFactory.fileProperty();
7676
releaseNotesFile = objectFactory.fileProperty();
7777
releaseHighlightsFile = objectFactory.fileProperty();
78-
breakingChangesFile = objectFactory.fileProperty();
78+
breakingChangesMigrationFile = objectFactory.fileProperty();
7979

8080
gitWrapper = new GitWrapper(execOperations);
8181
}
8282

8383
@TaskAction
8484
public void executeTask() throws IOException {
85-
if (needsGitTags(VersionProperties.getElasticsearch())) {
85+
final String currentVersion = VersionProperties.getElasticsearch();
86+
87+
if (needsGitTags(currentVersion)) {
8688
findAndUpdateUpstreamRemote(gitWrapper);
8789
}
8890

8991
LOGGER.info("Finding changelog files...");
9092

9193
final Map<QualifiedVersion, Set<File>> filesByVersion = partitionFilesByVersion(
9294
gitWrapper,
93-
VersionProperties.getElasticsearch(),
95+
currentVersion,
9496
this.changelogs.getFiles()
9597
);
9698

@@ -103,7 +105,7 @@ public void executeTask() throws IOException {
103105
changelogsByVersion.put(version, entriesForVersion);
104106
});
105107

106-
final Set<QualifiedVersion> versions = getVersions(gitWrapper, VersionProperties.getElasticsearch());
108+
final Set<QualifiedVersion> versions = getVersions(gitWrapper, currentVersion);
107109

108110
LOGGER.info("Updating release notes index...");
109111
ReleaseNotesIndexGenerator.update(
@@ -113,10 +115,12 @@ public void executeTask() throws IOException {
113115
);
114116

115117
LOGGER.info("Generating release notes...");
118+
final QualifiedVersion qualifiedVersion = QualifiedVersion.of(currentVersion);
116119
ReleaseNotesGenerator.update(
117120
this.releaseNotesTemplate.get().getAsFile(),
118121
this.releaseNotesFile.get().getAsFile(),
119-
changelogsByVersion
122+
qualifiedVersion,
123+
changelogsByVersion.getOrDefault(qualifiedVersion, Set.of())
120124
);
121125

122126
LOGGER.info("Generating release highlights...");
@@ -129,21 +133,22 @@ public void executeTask() throws IOException {
129133
LOGGER.info("Generating breaking changes / deprecations notes...");
130134
BreakingChangesGenerator.update(
131135
this.breakingChangesTemplate.get().getAsFile(),
132-
this.breakingChangesFile.get().getAsFile(),
136+
this.breakingChangesMigrationFile.get().getAsFile(),
133137
entries
134138
);
135139
}
136140

137141
/**
138-
* Find all tags in the `major.minor` series for the supplied version
142+
* Find all tags in the major series for the supplied version
139143
* @param gitWrapper used to call `git`
140144
* @param currentVersion the version to base the query upon
141145
* @return all versions in the series
142146
*/
143147
@VisibleForTesting
144148
static Set<QualifiedVersion> getVersions(GitWrapper gitWrapper, String currentVersion) {
145149
QualifiedVersion v = QualifiedVersion.of(currentVersion);
146-
Set<QualifiedVersion> versions = gitWrapper.listVersions("v" + v.getMajor() + '.' + v.getMinor() + ".*").collect(toSet());
150+
final String pattern = "v" + v.major() + ".*";
151+
Set<QualifiedVersion> versions = gitWrapper.listVersions(pattern).collect(toSet());
147152
versions.add(v);
148153
return versions;
149154
}
@@ -174,13 +179,16 @@ static Map<QualifiedVersion, Set<File>> partitionFilesByVersion(
174179
QualifiedVersion currentVersion = QualifiedVersion.of(versionString);
175180

176181
// Find all tags for this minor series, using a wildcard tag pattern.
177-
String tagWildcard = "v%d.%d*".formatted(currentVersion.getMajor(), currentVersion.getMinor());
182+
String tagWildcard = String.format(Locale.ROOT, "v%d.%d*", currentVersion.major(), currentVersion.minor());
178183

179184
final List<QualifiedVersion> earlierVersions = gitWrapper.listVersions(tagWildcard)
180185
// Only keep earlier versions, and if `currentVersion` is a prerelease, then only prereleases too.
181-
.filter(each -> each.isBefore(currentVersion) && (currentVersion.hasQualifier() == each.hasQualifier()))
186+
.filter(
187+
each -> each.isBefore(currentVersion)
188+
&& (currentVersion.isSnapshot() || (currentVersion.hasQualifier() == each.hasQualifier()))
189+
)
182190
.sorted(naturalOrder())
183-
.collect(toList());
191+
.toList();
184192

185193
if (earlierVersions.isEmpty()) {
186194
throw new GradleException("Failed to find git tags prior to [v" + currentVersion + "]");
@@ -339,11 +347,11 @@ public void setReleaseHighlightsFile(RegularFile file) {
339347
}
340348

341349
@OutputFile
342-
public RegularFileProperty getBreakingChangesFile() {
343-
return breakingChangesFile;
350+
public RegularFileProperty getBreakingChangesMigrationFile() {
351+
return breakingChangesMigrationFile;
344352
}
345353

346-
public void setBreakingChangesFile(RegularFile file) {
347-
this.breakingChangesFile.set(file);
354+
public void setBreakingChangesMigrationFile(RegularFile file) {
355+
this.breakingChangesMigrationFile.set(file);
348356
}
349357
}

0 commit comments

Comments
 (0)