Automate generating the `archetype-catalog.xml` file

[tasso94]

Context

The archetype-catalog.xml file hasn't been updated since last year. After switching from Nexus to the Artifactory repository, the archetype catalog is not updated with future releases.

Acceptance Criteria (Required on creation)

• The archetype-catalog.xml file is updated automatically on a regular basis to pick up new Automation Platform releases.
  • It needs to be updated minimally after each minor release (April and October).
• The catalog location on Artifactory is https://artifacts.camunda.com/artifactory/camunda-bpm/archetype-catalog.xml

Hints

• Initially reported issue: https://camunda.slack.com/archives/C5AHF1D8T/p1666781624765139
• In nexus, the update was made during index update?
• Artifactory doesn't offer an out-of-the-box solution for updating archetype catalogs

Solution ideas

Maven

1. Download the archetype-catalog.xml file to ~/.m2/repository/archetype-catalog.xml
2. Release the maven archetypes project: https://github.com/camunda/camunda-archetypes
   • This adds the new version to the archetype-catalog.xml file
3. Upload the file ~/.m2/repository/archetype-catalog.xml to Artifactory
   • The exact location is https://artifacts.camunda.com/artifactory/camunda-bpm/archetype-catalog.xml

To download the archetype-catalog.xml file, the Maven plugin com.googlecode.maven-download-plugin:download-maven-plugin might be useful. Uploading the changed file might be possible via the nexus stage plugin.

Other solutions

Solution ideas proposed by the INFRA team:

1. Use Artifactory API to get all archetypes of a repo
2. Use GitHub tags of the archetypes repo and create the XML via the language of your choice, as it's a fairly simple XML of 4 fields for each template

Links

This issue is created in favor of: https://github.com/camunda/team-infrastructure/issues/233

Breakdown

-

[yanavasileva]

1. To download the catalog:

     <plugin>
       <groupId>com.googlecode.maven-download-plugin</groupId>
       <artifactId>download-maven-plugin</artifactId>
       <version>1.3.0</version>
       <executions>
         <execution>
           <phase>process-resources</phase>
           <goals>
             <goal>wget</goal>
           </goals>
           <configuration>
             <url>https://artifacts.camunda.com/artifactory/camunda-bpm/archetype-catalog.xml</url>
             <outputFileName>archetype-catalog.xml</outputFileName>
             <outputDirectory>${catalog.path}</outputDirectory>
           </configuration>
         </execution>
       </executions>
     </plugin>

2. mvn install or mvn deploy populates the catalog with the new version

3. maven-deploy-plugin can be used to deploy the catalog. NOTE: I didn't test it However, we would like to skip upload when the version is SNAPSHOT so can create skip.catalog.deploy property for this purposes. The property can be used for the catalog download as well.

   
    <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>build-helper-maven-plugin</artifactId>
       <version>1.10</version>
       <executions>
         <execution>
           <id>bsh-property</id>
           <goals>
             <goal>bsh-property</goal>
           </goals>
           <configuration>
             <properties>
               <property>skip.catalog.deploy</property>
             </properties>
             <source>skip.catalog.deploy =
               project.getVersion().endsWith("-SNAPSHOT") ? true : false;</source>
           </configuration>
         </execution>
       </executions>
     </plugin>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-deploy-plugin</artifactId>
       <executions>
         <execution>
           <id>deploy-file</id>
           <phase>deploy</phase>
           <goals>
             <goal>deploy-file</goal>
           </goals>
           <configuration>
             <skip>${skip.catalog.deploy}</skip>
             <file>${catalog.path}\archetype-catalog.xml</file>
             <url>https://artifacts.camunda.com/artifactory/camunda-bpm/archetype-catalog.xml</url>
           </configuration>
         </execution>
       </executions>
     </plugin>

[tasso94]

The deploy-file goal fails if groupId, artifactId, and version are configured.

<configuration>
    <groupId>org.camunda.bpm.archetype</groupId>
    <artifactId>archetype-catalog</artifactId>
    <version>${project.version}</version>
   <!-- ... -->
</configuration>

Unfortunately, deploying a single plain file with the maven-deploy-plugin is impossible. The file's name is appended with a version and deployed to a location based on the artifactId and groupId. Additionally, a maven-metadata.xml file is deployed:

[INFO] --- maven-deploy-plugin:2.8.2:deploy-file (deploy-file) @ archetype-catalog ---
Downloading: file:~/org/camunda/bpm/archetype/archetype-catalog/7.19.0-SNAPSHOT/maven-metadata.xml
Downloaded: file:~/org/camunda/bpm/archetype/archetype-catalog/7.19.0-SNAPSHOT/maven-metadata.xml (621 B at 86.6 KB/sec)
Uploading: file:~/org/camunda/bpm/archetype/archetype-catalog/7.19.0-SNAPSHOT/archetype-catalog-7.19.0-20230123.142831-2.xml
Uploaded: file:~/org/camunda/bpm/archetype/archetype-catalog/7.19.0-SNAPSHOT/archetype-catalog-7.19.0-20230123.142831-2.xml (91 KB at 30303.1 KB/sec)
Downloading: file:~/org/camunda/bpm/archetype/archetype-catalog/maven-metadata.xml
Downloaded: file:~/org/camunda/bpm/archetype/archetype-catalog/maven-metadata.xml (303 B at 295.9 KB/sec)
Uploading: file:~/org/camunda/bpm/archetype/archetype-catalog/7.19.0-SNAPSHOT/maven-metadata.xml
Uploaded: file:~/org/camunda/bpm/archetype/archetype-catalog/7.19.0-SNAPSHOT/maven-metadata.xml (621 B at 606.4 KB/sec)
Uploading: file:~/org/camunda/bpm/archetype/archetype-catalog/maven-metadata.xml
Uploaded: file:~/org/camunda/bpm/archetype/archetype-catalog/maven-metadata.xml (303 B at 295.9 KB/sec)

We need to decide on the following points:

• Is it acceptable for the archetype-catalog.xml files to be deployed at another place than https://artifacts.camunda.com/artifactory/camunda-bpm/archetype-catalog.xml?
  • New location: https://artifacts.camunda.com/artifactory/camunda-bpm/org/camunda/bpm/archetype/archetype-catalog/7.19.0/archetype-catalog-7.19.0.xml
• Is it acceptable to version the archetype-catalog.xml files instead of having a single file that contains all the versions?
  • For legacy reasons, we could keep the old catalog file, but archetypes starting with a specific version would be stored at a different location.

[tasso94]

Prototype: https://github.com/camunda/camunda-archetypes/commit/d1402522966e6f9c23423f0971ae938bcd31742a