Skip to content

Commit 8fbd201

Browse files
sebersolesebersole
committed
HHH-18485 - Documentation symlinks on release
1 parent 1718e88 commit 8fbd201

7 files changed

+295
-55
lines changed

‎local-build-plugins/src/main/java/org/hibernate/orm/ReleaseFamilyIdentifier.java

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
package org.hibernate.orm;
88

99
import java.io.Serializable;
10+
import java.util.Objects;
1011

1112
/**
1213
* Major/family version component pair
@@ -45,6 +46,23 @@ public String toExternalForm() {
4546
return majorVersion + "." + familyVersion;
4647
}
4748

49+
@Override
50+
public boolean equals(Object o) {
51+
if ( this == o ) {
52+
return true;
53+
}
54+
if ( o == null || getClass() != o.getClass() ) {
55+
return false;
56+
}
57+
ReleaseFamilyIdentifier that = (ReleaseFamilyIdentifier) o;
58+
return majorVersion == that.majorVersion && familyVersion == that.familyVersion;
59+
}
60+
61+
@Override
62+
public int hashCode() {
63+
return Objects.hash( majorVersion, familyVersion );
64+
}
65+
4866
public boolean newerThan(ReleaseFamilyIdentifier other) {
4967
return compareTo( other ) > 0;
5068
}

‎local-build-plugins/src/main/java/org/hibernate/orm/docs/DescriptorAccess.java

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@
2020
import org.apache.http.impl.client.HttpClientBuilder;
2121

2222
/**
23-
* Models the published doc descriptor file
23+
* Helper for {@linkplain #loadProject() loading} the project documentation descriptor and
24+
* {@linkplain #storeProject storing} it to file.
2425
*
2526
* @author Steve Ebersole
2627
*/
@@ -46,6 +47,9 @@ public static ProjectDocumentationDescriptor loadProject() {
4647
}
4748
}
4849

50+
/**
51+
* Store the descriptor to file
52+
*/
4953
public static void storeProject(ProjectDocumentationDescriptor project, File jsonFile) {
5054
prepareJsonFile( jsonFile );
5155

‎local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishing.java

Lines changed: 30 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,21 @@
2525
public class DocumentationPublishing {
2626
public static final String DSL_NAME = "documentationPublishing";
2727

28+
public static final String RSYNC_SERVER = "filemgmt-prod-sync.jboss.org";
29+
public static final String SFTP_SERVER = "filemgmt-prod.jboss.org";
30+
31+
public static final String DOC_SERVER_BASE_DIR = "/docs_htdocs/hibernate";
32+
33+
public static final String DESCRIPTOR_FILE = "doc-pub/orm.json";
34+
2835
private final Project project;
2936

3037
private final DirectoryProperty stagingDirectory;
31-
private final Property<String> docServerUrl;
3238

33-
private final Property<String> docDescriptorUploadUrl;
39+
private final Property<String> rsyncDocServer;
40+
private final Property<String> sftpDocServer;
41+
private final Property<String> serverBaseDir;
42+
3443
private final RegularFileProperty updatedJsonFile;
3544

3645
private final ReleaseFamilyIdentifier releaseFamilyIdentifier;
@@ -43,18 +52,22 @@ public DocumentationPublishing(Project project) {
4352
.directoryProperty()
4453
.convention( project.getLayout().getBuildDirectory().dir( "documentation" ) );
4554

46-
docServerUrl = project.getObjects()
55+
56+
rsyncDocServer = project.getObjects()
4757
.property( String.class )
48-
.convention( "filemgmt-prod-sync.jboss.org:/docs_htdocs/hibernate/orm" );
58+
.convention( RSYNC_SERVER );
4959

50-
docDescriptorUploadUrl = project.getObjects()
60+
sftpDocServer = project.getObjects()
5161
.property( String.class )
52-
.convention( "filemgmt-prod-sync.jboss.org:/docs_htdocs/hibernate/_outdated-content/orm.json" );
62+
.convention( SFTP_SERVER );
5363

64+
serverBaseDir = project.getObjects()
65+
.property( String.class )
66+
.convention( DOC_SERVER_BASE_DIR );
5467

5568
updatedJsonFile = project.getObjects()
5669
.fileProperty()
57-
.convention( project.getLayout().getBuildDirectory().file( "doc-pub/orm.json" ) );
70+
.convention( project.getLayout().getBuildDirectory().file( DESCRIPTOR_FILE ) );
5871

5972
releaseFamilyIdentifier = ReleaseFamilyIdentifier.parse( project.getVersion().toString() );
6073
}
@@ -63,24 +76,22 @@ public ReleaseFamilyIdentifier getReleaseFamilyIdentifier() {
6376
return releaseFamilyIdentifier;
6477
}
6578

66-
public Property<String> getDocServerUrl() {
67-
return docServerUrl;
79+
public Property<String> getRsyncDocServer() {
80+
return rsyncDocServer;
6881
}
6982

70-
public DirectoryProperty getStagingDirectory() {
71-
return stagingDirectory;
83+
public Property<String> getSftpDocServer() {
84+
return sftpDocServer;
85+
}
86+
87+
public Property<String> getServerBaseDir() {
88+
return serverBaseDir;
7289
}
7390

74-
/**
75-
* Where to upload the {@link #getUpdatedJsonFile() documentation descriptor}
76-
*/
77-
public Property<String> getDocDescriptorUploadUrl() {
78-
return docDescriptorUploadUrl;
91+
public DirectoryProperty getStagingDirectory() {
92+
return stagingDirectory;
7993
}
8094

81-
/**
82-
* THe ORM documentation descriptor
83-
*/
8495
public Provider<RegularFile> getUpdatedJsonFile() {
8596
return updatedJsonFile;
8697
}

‎local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishingPlugin.java

Lines changed: 51 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,11 @@
66
*/
77
package org.hibernate.orm.docs;
88

9+
import java.util.Locale;
10+
911
import org.gradle.api.Plugin;
1012
import org.gradle.api.Project;
13+
import org.gradle.api.provider.Provider;
1114
import org.gradle.api.tasks.TaskProvider;
1215

1316
import static org.hibernate.orm.docs.DocumentationPublishing.DSL_NAME;
@@ -17,10 +20,12 @@
1720

1821
/**
1922
* Plugin for helping with publishing documentation to the doc server - <ul>
20-
* <li>Publishes a config extension ({@link DocumentationPublishing}) under {@value DocumentationPublishing#DSL_NAME}</li>
21-
* <li>Creates a task ({@value PublishTask#UPLOAD_TASK_NAME}) to upload the documentation to the doc server</li>
22-
* <li>Creates a task ({@value GenerateDescriptorTask#GEN_DESC_TASK_NAME}) to create the "published doc descriptor" (JSON) file</li>
23-
* <li>Creates a task ({@value PublishDescriptorTask#UPLOAD_DESC_TASK_NAME}) to upload the "published doc descriptor" (JSON) file to the doc server</li>
23+
* <li>Publishes a {@link DocumentationPublishing DSL extension} under {@value DocumentationPublishing#DSL_NAME}</li>
24+
* <li>Creates a task to upload the documentation to the doc server - {@value PublishTask#UPLOAD_TASK_NAME}</li>
25+
* <li>Creates a task to create the doc descriptor (JSON) file - {@value GenerateDescriptorTask#GEN_DESC_TASK_NAME}</li>
26+
* <li>Creates a task to upload the doc descriptor (JSON) file to the doc server - {@value PublishDescriptorTask#UPLOAD_DESC_TASK_NAME}</li>
27+
* <li>Creates a task to update symlinks on the doc server - {@value UpdateSymLinksTask#SYMLINKS_TASK_NAME}</li>
28+
* <li>Creates a task to upload the migration guide to the doc server - {@value PublishMigrationGuide#NAME}</li>
2429
* </ul>
2530
*
2631
* @author Steve Ebersole
@@ -31,36 +36,28 @@ public void apply(Project project) {
3136
final DocumentationPublishing docPubDsl = project.getExtensions().create( DSL_NAME, DocumentationPublishing.class );
3237

3338
final boolean isSnapshot = project.getVersion().toString().endsWith( "-SNAPSHOT" );
39+
final boolean isFinal = project.getVersion().toString().endsWith( ".Final" );
3440

3541
final TaskProvider<GenerateDescriptorTask> generateDescriptorTask = project.getTasks().register(
3642
GEN_DESC_TASK_NAME,
3743
GenerateDescriptorTask.class,
3844
(task) -> {
3945
task.getCurrentlyBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
4046
task.getJsonFile().convention( docPubDsl.getUpdatedJsonFile() );
47+
48+
task.onlyIf( (t) -> isFinal );
4149
}
4250
);
4351

4452
final TaskProvider<PublishDescriptorTask> uploadDescriptorTask = project.getTasks().register(
4553
UPLOAD_DESC_TASK_NAME,
4654
PublishDescriptorTask.class,
4755
(task) -> {
48-
task.getDocDescriptorUploadUrl().convention( docPubDsl.getDocDescriptorUploadUrl() );
56+
task.getDocDescriptorUploadUrl().convention( defaultDescriptorUploadUrl( docPubDsl ) );
4957
task.getJsonFile().convention( docPubDsl.getUpdatedJsonFile() );
5058

5159
task.dependsOn( generateDescriptorTask );
52-
task.onlyIf( (t) -> !isSnapshot && generateDescriptorTask.get().getDidWork() );
53-
}
54-
);
55-
56-
//noinspection unused
57-
final TaskProvider<PublishMigrationGuide> publishMigrationGuideTask = project.getTasks().register(
58-
PublishMigrationGuide.NAME,
59-
PublishMigrationGuide.class,
60-
(task) -> {
61-
task.getCurrentlyBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
62-
task.getDocServerUrl().convention( docPubDsl.getDocServerUrl() );
63-
task.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "documentation/migration-guide" ) );
60+
task.onlyIf( (t) -> generateDescriptorTask.get().getDidWork() && generateDescriptorTask.get().needsUpload() );
6461
}
6562
);
6663

@@ -70,12 +67,48 @@ public void apply(Project project) {
7067
PublishTask.class,
7168
(task) -> {
7269
task.getBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
73-
task.getDocServerUrl().convention( docPubDsl.getDocServerUrl() );
7470
task.getStagingDirectory().convention( docPubDsl.getStagingDirectory() );
71+
task.getDocServerUrl().convention( defaultDocUploadUrl( docPubDsl ) );
7572

7673
task.dependsOn( uploadDescriptorTask );
7774
task.onlyIf( (t) -> !isSnapshot );
7875
}
7976
);
77+
78+
//noinspection unused
79+
final TaskProvider<UpdateSymLinksTask> symLinkTask = project.getTasks().register(
80+
UpdateSymLinksTask.SYMLINKS_TASK_NAME,
81+
UpdateSymLinksTask.class,
82+
(task) -> {
83+
task.getBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
84+
task.getSftpDocServer().convention( docPubDsl.getSftpDocServer() );
85+
task.getServerBaseDir().convention( docPubDsl.getServerBaseDir() );
86+
87+
task.dependsOn( generateDescriptorTask );
88+
task.dependsOn( uploadTask );
89+
task.onlyIf( (t) -> generateDescriptorTask.get().getDidWork() && generateDescriptorTask.get().needsSymLinkUpdate() );
90+
}
91+
);
92+
93+
//noinspection unused
94+
final TaskProvider<PublishMigrationGuide> publishMigrationGuideTask = project.getTasks().register(
95+
PublishMigrationGuide.NAME,
96+
PublishMigrationGuide.class,
97+
(task) -> {
98+
task.getCurrentlyBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
99+
task.getDocServerUrl().convention( defaultDocUploadUrl( docPubDsl ) );
100+
task.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "documentation/migration-guide" ) );
101+
}
102+
);
103+
}
104+
105+
private Provider<String> defaultDescriptorUploadUrl(DocumentationPublishing dsl) {
106+
return dsl.getRsyncDocServer()
107+
.map( (server) -> String.format( Locale.ROOT, "%s:%s/_outdated-content/orm.json", server, dsl.getServerBaseDir().get() ) );
108+
}
109+
110+
private Provider<String> defaultDocUploadUrl(DocumentationPublishing dsl) {
111+
return dsl.getRsyncDocServer()
112+
.map( (server) -> String.format( Locale.ROOT, "%s:%s/orm", server, dsl.getServerBaseDir().get() ) );
80113
}
81114
}

‎local-build-plugins/src/main/java/org/hibernate/orm/docs/GenerateDescriptorTask.java

Lines changed: 62 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
package org.hibernate.orm.docs;
88

99
import java.io.File;
10+
import java.util.HashSet;
11+
import java.util.Iterator;
12+
import java.util.Set;
1013

1114
import org.gradle.api.DefaultTask;
1215
import org.gradle.api.file.RegularFileProperty;
@@ -18,19 +21,25 @@
1821
import org.hibernate.orm.ReleaseFamilyIdentifier;
1922

2023
/**
24+
* Task for creating the JSON "documentation descriptor" for ORM
25+
*
2126
* @author Steve Ebersole
2227
*/
2328
public abstract class GenerateDescriptorTask extends DefaultTask {
2429
public static final String GEN_DESC_TASK_NAME = "generateDocumentationDescriptor";
25-
private final RegularFileProperty jsonFile;
30+
2631
private final Property<ReleaseFamilyIdentifier> currentlyBuildingFamily;
32+
private final RegularFileProperty jsonFile;
33+
34+
private boolean needsUpload;
35+
private boolean needsSymLinkUpdate;
2736

2837
public GenerateDescriptorTask() {
2938
setGroup( "documentation" );
3039
setDescription( "Generates the documentation publication descriptor (JSON)" );
3140

32-
jsonFile = getProject().getObjects().fileProperty();
3341
currentlyBuildingFamily = getProject().getObjects().property( ReleaseFamilyIdentifier.class );
42+
jsonFile = getProject().getObjects().fileProperty();
3443
}
3544

3645
@Input
@@ -43,14 +52,47 @@ public RegularFileProperty getJsonFile() {
4352
return jsonFile;
4453
}
4554

55+
/**
56+
* Whether we determined, during {@linkplain #generateDescriptor}, that uploading the
57+
* doc descriptor was needed.
58+
*
59+
* @see PublishDescriptorTask
60+
*/
61+
public boolean needsUpload() {
62+
return getDidWork() && needsUpload;
63+
}
64+
65+
/**
66+
* Whether we determined, during {@linkplain #generateDescriptor}, that updating the
67+
* doc server symlinks was needed.
68+
*
69+
* @see UpdateSymLinksTask
70+
*/
71+
public boolean needsSymLinkUpdate() {
72+
return getDidWork() && needsSymLinkUpdate;
73+
}
74+
4675
@TaskAction
4776
public void generateDescriptor() {
4877
final ProjectDocumentationDescriptor descriptor = DescriptorAccess.loadProject();
78+
final boolean isFinal = getProject().getVersion().toString().endsWith( ".Final" );
4979

80+
final Set<ReleaseFamilyIdentifier> processedReleases = new HashSet<>();
5081
ReleaseFamilyIdentifier newest = null;
5182
boolean foundCurrentRelease = false;
5283

53-
for ( ReleaseFamilyDocumentation releaseFamily : descriptor.getReleaseFamilies() ) {
84+
final Iterator<ReleaseFamilyDocumentation> itr = descriptor.getReleaseFamilies().iterator();
85+
while ( itr.hasNext() ) {
86+
final ReleaseFamilyDocumentation releaseFamily = itr.next();
87+
88+
// NOTE: sometimes releases get duplicated in the descriptor...
89+
// let's clean those up if we run across them
90+
if ( !processedReleases.add( releaseFamily.getName() ) ) {
91+
itr.remove();
92+
needsUpload = true;
93+
continue;
94+
}
95+
5496
if ( newest == null
5597
|| releaseFamily.getName().newerThan( newest ) ) {
5698
newest = releaseFamily.getName();
@@ -61,27 +103,31 @@ public void generateDescriptor() {
61103
}
62104
}
63105

64-
if ( ! foundCurrentRelease ) {
65-
final ReleaseFamilyDocumentation newEntry = new ReleaseFamilyDocumentation();
66-
newEntry.setName( currentlyBuildingFamily.get() );
67-
descriptor.addReleaseFamily( newEntry );
68-
setDidWork( true );
69-
}
106+
if ( isFinal ) {
107+
// we are releasing a Final - possibly do some other things
70108

71-
// we only want to update "stable" to `currentlyBuildingFamily` when-
72-
// 1. we are currently building a Final
73-
// 2. currentlyBuildingFamily is the newest
109+
if ( !foundCurrentRelease ) {
110+
// this release is not yet tracked in the descriptor - add it
111+
final ReleaseFamilyDocumentation newEntry = new ReleaseFamilyDocumentation();
112+
newEntry.setName( currentlyBuildingFamily.get() );
113+
descriptor.addReleaseFamily( newEntry );
114+
setDidWork( true );
115+
needsUpload = true;
116+
}
74117

75-
if ( currentlyBuildingFamily.get().newerThan( newest ) ) {
76-
descriptor.setStableFamily( currentlyBuildingFamily.get() );
77-
setDidWork( true );
118+
if ( currentlyBuildingFamily.get().newerThan( newest ) ) {
119+
// this release is newer than any currently tracked in the descriptor
120+
descriptor.setStableFamily( currentlyBuildingFamily.get() );
121+
setDidWork( true );
122+
needsSymLinkUpdate = true;
123+
}
78124
}
79125

80126
DescriptorAccess.storeProject( descriptor, jsonFile.get().getAsFile() );
81127
}
82128

83129
public static void main(String... args) {
84-
final File jsonFile = new File( "/home/sebersole/projects/hibernate-orm/6.0/hibernate-orm-build/target/doc-pub/orm.json" );
130+
final File jsonFile = new File( "/tmp/hibernate-orm-build/doc-pub/orm.json" );
85131
final ProjectDocumentationDescriptor projectDoc = DescriptorAccess.loadProject();
86132
DescriptorAccess.storeProject( projectDoc, jsonFile );
87133
}

0 commit comments

Comments
 (0)