Uploaded image for project: 'Spring Tool Suite'
  1. Spring Tool Suite
  2. STS-2713

write user documentation on how to set up a template project on GitHub



    • Type: Improvement
    • Status: Resolved
    • Priority: Minor
    • Resolution: Won't Fix
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: SUPPORT
    • Labels:


      Users will have the ability to create template projects and self-host them and, eventually, upload them to GitHub. Understanding how everything fits together is important, and we don't have any end-user documentation on how to do that. We need to explain:

      • The format of the template.xml and/or descriptors.xml files.
      • The format of the wizard.json file.
        • The new project name in the wizard.json file must match the package/import statements in the source, or unexpected things will happen. For example, if you specify (via the pattern regexp) that the user must enter a package with four elements (e.g. "mytld.mycompany.myapp.mycomponent"), yet the base package directory in src/java is "mytld.mycompany.myapp", if the user enters "a.b.c.d" for the new package name, in the java file, they will only see "package a.b.c". This might surprise them.
      • When the template is imported, strings in the downloaded template will be replaced to correspond to the new package/project name.
        • The old package name is taken from the wizard.json file's topLevelPackage field. The old project name is taken from the wizard.json's projectName field. The new package name and the new project name are taken from user input when they fill out the wizard (which comes up after you say that yes, you want to download the project).
        • WARNING! The code uses simple string replacements. Thus, if you give an old package name of "com.ducky.file.foo", and the user types in a new package name of "org.hangarhonchos.newfile.bar", then user's elements "computeAttribute()", "@author ducky", and "fileHandle" will be replaced with "orgputeAttribute()", "@author hangarhonchos", and "newfileHandle". Take care that the old names you put into templates don't appear elsewhere in the source.
      • git ignores empty directories. If you need your template to have an empty directory, you need to make it not empty by putting some dummy file into it (e.g. ".ignore" or ".hangarhonchosIgnoreThis").
      • Remember your dot files. Shells sometimes leave them out (or don't show them), so if you aren't careful you might not get files like .project uploaded to github.




            mlippert Martin Lippert
            kaitlinsherwood Kaitlin Duck Sherwood
            0 Vote for this issue
            3 Start watching this issue