Ben Jackson <[email protected]> írta: >Hi, Dan and Woonsan > >Thanks for all of the feedback. > >1. Yes, the current design is one output source file per json data file. >2. We would intend to use the open source version and update as needed. >3. We don't anticipate any significant development to meet our needs. As >you said, this is a fairly simple concept. I could imagine some other use >case that would need some tweaks. We would be able to support the plugin as >needed.
Participating in decisions, in case someone here wants to change things, would be important. I mean, in your own interest, because some changes might not good for your use case. In general, people who invest more into a project has more weight in such discussions. >My questions / assumptions. > >1. I assume we would host this as a separate repository under the >apache project, say apache/freemarker-maven-plugn. Is this right? Yes. (At least in the 2.x branch that's the policy. But for now we only do this there anyway.) >2. I assume the plugin would follow an independent release cycle...would >you manage the publication throug the existing freemarker project >credentials? Yes, it would have an independent release cycle, and same credentials. >3. Would you want us to use some specific CI/CD process for the project? >If so, is it documented somewhere? It isn't documented, but a Travis CI build would be good. Also a coverage report icon, for that mater. >4. I assume we would need to update the Freemarker website with >documentation; The documentation of this tool wouldn't be part of the FreeMarker Manual (https://freemarker.apache.org/docs/). But I would create something like https://freemarker.apache.org/maven-plugin/index.html to hold the documentation and such. It should use use DocBook format and Docgen, as the "freemarker" and "freemarker-site" projects do it. (See also in freemarker-docgen.) The generated documentation is then just manually uploaded into that directory. Well, I guess that part (Docgen and all) is somewhat scary, but I can make the initial version. >I will have Mark and Myself sign CLAs through our open source team to >contribute to Freemarker; I will tweak the packaging and copyright to >something appropriate, and we can then share the source with you. I will >also review the recommended properties at https://freemarker.apache.org/ >docs/pgui_quickstart_createconfiguration.html. > > >-Ben > > > > > > > >On Wed, Aug 15, 2018 at 1:42 PM, Daniel Dekany <[email protected]> wrote: > >> It's quite focused on the specific use case, but I guess many use >> cases where FreeMarker is involved with Maven is similar. (Or not... I >> don't have the data to tell honestly.) Anyway, as an internal project >> it's expected to be specialized on one case. Things can be >> generalized/extended further after contribution. (Then of course >> question is if the existing solution is solid enough so that it worths >> building upon it, or it will be refactored beyond recognition. But >> this we can try to guess if we see the source code.) >> >> Another important question is if what are the plans of your company >> with this plugin. Let's say this comes to Apache. After that, do you >> plan to use the Apache version of the plugin, contributing to it when >> you need some improvement? Is such a thing expected at all, or you >> don't expect that you will develop the plugin further? Any of you is >> interested to improve it regardless, in your free time? >> >> A note regarding the the default FreeMarker configuration... I would >> recommend setting a few more things according to >> https://freemarker.apache.org/docs/pgui_quickstart_ >> createconfiguration.html. >> >> >> Tuesday, August 14, 2018, 6:08:21 PM, Ben Jackson wrote: >> >> > Hello, >> > >> > My colleague Mark Malynn (CC’d) has been using apache Freemarker on an >> > internal Oath (e.g. Yahoo/AOL) project that we are intending to open >> > source. This project is an Immutable Offheap Cache which is used to store >> > and access data off-heap for high-performance java server applications. >> > >> > As a part of our offering, we provide out of the box primitive >> collections >> > classes that mirror FastUtils, and we are using Freemarker to generate >> > source files needed to implement those primitive collections. >> > >> > Mark built a Maven plugin for Freemarker that we use as a part of our >> build >> > process. We built this because the Freemarker project does not provide >> one >> > natively and other plugins we found do not offer the power level we >> needed >> > (we generate sources from multiple templates during both build and test >> > phases of the pipeline). >> > >> > When working with our internal open sourcing team, they suggested that we >> > first reach out to you to gauge interest in hosting this plugin as a part >> > of the Freemarker project. This made sense to us as well. >> > >> > Please let us know if it makes sense to contribute this as a part of >> > Freemarker. We can support it as needed. >> > >> > Below the is the existing project README.md: >> > freemarker-maven-plugin Background >> > >> > This plugin is used to generate files using FreeMarker template files and >> > JSON data files. >> > FreeMarker Template Files >> > >> > FreeMarker template files must reside in the template sub-directory under >> > the sourceDirectory. For the default configuration, this is: >> > src/main/freemarker/template. >> > >> > By convention, file names for FreeMarker template files use the .ftl >> > extension. For details on the FreeMarker template syntax, see: Getting >> > Started <https://freemarker.apache.org/docs/dgui_quickstart.html> and >> > Template Language Reference >> > <https://freemarker.apache.org/docs/ref.html>. >> > JSON Data Files >> > >> > The JSON data files must reside in the data sub-directory under >> > sourceDirectory. For the default configuration, this is: >> > src/main/freemarker/data. >> > >> > For each JSON data file, freemarker-maven-plugin will generate a file >> under >> > the outputDirectory. The name of the generated file will be based on the >> > name of the JSON data file. For example, the following JSON file: >> > >> > <sourceDirectory>/data/my/package/MyClass.java.json >> > >> > will result in the following file being generated: >> > >> > <outputDirectory>/my/package/MyClass.java >> > >> > This plugin parses the JSON data file into a Map<String, Object> instance >> > (hereafter, referred >> > to as the data map). The parser allows for comments. After parsing the >> > file, the plugin will add >> > a pomProperties entry into the data map, which is itself a map containing >> > the properties defined in the pom. Thus, your template can reference the >> > pom property my_property using >> > ${pomProperties.my_property}. If you have a period or dash in the >> property >> > name, use >> > ${pomProperties["my.property"]}. >> > >> > This plugin requires one top-level field in the JSON data file: >> templateName. >> > This field >> > is used to locate the template file under <sourceDirectory>/template that >> > is used to generate >> > the file. This plugin provides the data map to FreeMarker as the data >> model >> > to process the template identified by templateName. >> > >> > This plugin currently assumes that the JSON data file encoded using >> UTF-8. >> > >> > Example JSON data file: >> > >> > { >> > // An end-of-line comment. >> > # Another end-of-line comment >> > "templateName": "my-template.ftl", >> > /* A multi-line >> > comment */ >> > "myString": "a string", >> > "myNumber": 1, >> > "myListOfStrings": ["s1", "s2"], >> > "myListOfNumbers": [1, 2], >> > "myMap": { >> > "key1": "value1", >> > "key2": 2 >> > } >> > } >> > >> > Installation pom.xml >> > >> > Add the following snippet within the <plugins> tag of your pom.xml: >> > >> > <plugin> >> > <groupId>com.oath</groupId> >> > <artifactId>freemarker-maven-plugin</artifactId> >> > <version>${freemarker-maven-plugin.version}</version> >> > <configuration> >> > <!-- Required. Specifies the compatibility version for >> > template processing --> >> > <freeMarkerVersion>2.3.23</freeMarkerVersion> >> > </configuration> >> > <executions> >> > <!-- If you want to generate files during other phases, just >> > add more execution >> > tags and specify appropriate phase, sourceDirectory and >> > outputDirectory values. >> > --> >> > <execution> >> > <id>freemarker</id> >> > <!-- Optional, defaults to generate-sources --> >> > <phase>generate-sources</phase> >> > <goals> >> > <!-- Required, must be generate --> >> > <goal>generate</goal> >> > </goals> >> > <configuration> >> > <!-- Optional, defaults to src/main/freemarker --> >> > <sourceDirectory>src/main/freemarker</sourceDirectory> >> > <!-- Optional, defaults to >> > target/generated-sources/freemarker --> >> > >> > <outputDirectory>target/generated-sources/freemarker</outputDirectory> >> > </configuration> >> > </execution> >> > </executions> >> > </plugin> >> > >> > Usage FreeMarker Configuration >> > >> > Typically, users of this plugin do not need to mess with the FreeMarker >> > configuration. This plugin explicitly sets two FreeMarker configurations: >> > >> > 1. the default encoding is set to UTF-8 >> > 2. the template loader is set to be a FileTemplateLoader that reads >> from >> > <sourceDirectory>/template. >> > >> > If you need to override these configs or set your own, you can put them >> in a >> > <sourceDirectory>/freemarker.properties file. If that file exists, this >> > plugin will read it into >> > a java Properties instance and pass it to >> > freemarker.core.Configurable.setSettings() to establish >> > the FreeMarker configuration. See this javadoc >> > <https://freemarker.apache.org/docs/api/freemarker/ >> template/Configuration.html#setSetting-java.lang.String-java.lang.String-> >> > for configuration details. >> > Code Coverage >> > >> > By default the code coverage report is not generated. You can generate >> code >> > coverage on your dev machine with the following maven command: >> > >> > mvn clean initialize -Dclover-phase=initialize >> > >> > Bring up the coverage report by pointing your browser to >> > target/site/clover/dashboard.html >> > under the root directory of the local repository. >> > Contribute >> > >> > See Contributing.md >> > License >> > >> > Licenced under the Apache 2.0 license. See: LICENSE.txt >> > >> > — >> > Benjamin Grant Jackson >> >> -- >> Thanks, >> Daniel Dekany >> >> > > >-- >Benjamin Grant Jackson >
