Bug 193981 - Project license cannot be shared
Project license cannot be shared
Status: RESOLVED FIXED
Product: projects
Classification: Unclassified
Component: Generic Projects UI
7.0
PC Linux
: P2 (vote)
: 7.4
Assigned To: Milos Kleint
issues@projects
: API, API_REVIEW_FAST
Depends on:
Blocks: 226773 226774
  Show dependency treegraph
 
Reported: 2011-01-03 15:10 UTC by _ rkubacki
Modified: 2013-03-01 02:01 UTC (History)
1 user (show)

See Also:
Issue Type: ENHANCEMENT
:


Attachments
patch to RsrcLoader (1.67 KB, patch)
2013-01-25 15:50 UTC, Milos Kleint
Details | Diff
patch to loaders, freemarker + ant and maven/ant projects (16.60 KB, patch)
2013-02-18 10:38 UTC, Milos Kleint
Details | Diff
entire patch for main repository (60.45 KB, patch)
2013-02-18 10:39 UTC, Milos Kleint
Details | Diff
updated patch to core modules (18.98 KB, application/octet-stream)
2013-02-25 21:02 UTC, Milos Kleint
Details

Note You need to log in before you can comment on or make changes to this bug.
Description _ rkubacki 2011-01-03 15:10:38 UTC
There are few blog post explaining how to set up templates in IDE project to create new files with proper license header but all of them have one serious limitation: the license is not shared in project. My customized template has to refer to something what is locally stored in my installation / userdir. 

I believe it is common that licenses are applied to project and that means it is part of shared project configuration.
Comment 1 Jesse Glick 2011-01-12 04:03:59 UTC
Not a problem for Maven projects.
Comment 2 Milos Kleint 2013-01-25 10:24:55 UTC
the major problem with project space license header templates is how such files are supposed to be treated in multiprojects. With ant references to other projects are more easier to be done, in maven projects , it's mostly a challenge that is being fought by some current plugins with non optimal results..

I suppose in ant projects, the license header file should reside in nbproject/ directory.
Comment 3 Milos Kleint 2013-01-25 13:50:36 UTC
file templates currently contain following freemarker instruction:
<#include "../Licenses/license-${project.license}.txt">
That includes a given license template into the file template, please note the relative path specified. When the template is declared deeper in the template folder hierarchy, the path changes.

In order to support project specific license headers we would need to declare absolute path here. With current codebase that appears to be working by declaring 
<#include "/Templates/Licenses/license-${project.license}.txt">

So the way to project located license header template is to create a new property next to project.license, for example project.licensePath. By default it would contain the value above. But would be overridable from project.

However changes to org.netbeans.libs.freemarker.RsrcLoader are needed as currently only files from layer filesystem can be resolved (only files sharing filesystem with the template to be specific)
Comment 4 Milos Kleint 2013-01-25 15:50:42 UTC
Created attachment 130655 [details]
patch to RsrcLoader
Comment 5 Milos Kleint 2013-01-25 15:52:15 UTC
the attached patch allow entering the path to license template as url :
<#include "file:///Users/mkleint/license.txt">
That can be exploited by projects eventually via a property
Comment 6 Jaroslav Tulach 2013-01-28 08:35:07 UTC
We will have to modify all our existing templates. When doing that it would be better to do it right - e.g. make the change flexible enough. I'd like it also support maven-license-plugin like in http://source.apidesign.org/hg/bck2brwsr/file/5e13b1ac2886/pom.xml#l56, if possible. Miloš told me about possible problems (inherit=false, too much supported formats in the plugin), but hopefully we can overcome that.
Comment 7 Milos Kleint 2013-02-18 10:38:46 UTC
Created attachment 131524 [details]
patch to loaders, freemarker + ant and maven/ant projects

attached is a patch to loaders+freemarker that allows setting project aligned license templates, including backend support in ant and maven projects.

now 2 possibilities are supported. The current one with just specifying the name of the license and looking it up in netbeans configuration space (user directory), but also a new one where a file on the filesystem can be used, typically one related to the project location.

entire core-main patch with changed templates follows
Comment 8 Milos Kleint 2013-02-18 10:39:15 UTC
Created attachment 131525 [details]
entire patch for main repository
Comment 9 Milos Kleint 2013-02-18 10:43:51 UTC
please review this change in file templates. Currently no apichanges document updated, not sure if a new freemarker property is to be listed in openide.loaders or in libs.freemarker. I haven't found the existing properties documented anywhere either. (maybe arch.xml is the right place?)
Comment 10 Jaroslav Tulach 2013-02-25 04:34:41 UTC
Y01 The existing property is defined in projectuiapi/arch.xml. 

Y02 Given Y02, I'd suggest to use "project.license.path" property in the patch and describe it in projectuiapi/arch.xml as well

Y03 I (as a user) am using com.mycila.maven-license-plugin. I have a feeling it is de-facto standard license management tool for Maven and it would be nice for project.license.path to co-operate well with it at least in simple case (no inherit, etc.).
Comment 11 Milos Kleint 2013-02-25 07:16:12 UTC
(In reply to comment #10)
> Y01 The existing property is defined in projectuiapi/arch.xml. 

I see, that's why I didn't find it. That's fairly out of place location given current behaviour. Neither templates nor the CreateFromTemplateAttributesProvider interface are project specific nowadays.

> 
> Y02 Given Y02, I'd suggest to use "project.license.path" property in the patch
> and describe it in projectuiapi/arch.xml as well

you mean the "licensePath" template attribute value as included in the templates? for the reasons above, I suggest we either move the existing template attributes to the loaders or add the new one to loaders and reference the pre-existing ones from there.

I've used a single "word" here because anything separated by a dot ends up being nested maps. I assume the original purpose of the dot convention was to traverse object trees but we don't have any project instance with license property.

> 
> Y03 I (as a user) am using com.mycila.maven-license-plugin. I have a feeling it
> is de-facto standard license management tool for Maven and it would be nice for
> project.license.path to co-operate well with it at least in simple case (no
> inherit, etc.).

That's out of scope for the current api review. That's limited to the maven implementation of CreateFromTemplateAttributesProvider and it's bridging the content of the maven plugin.
Comment 12 Milos Kleint 2013-02-25 11:47:56 UTC
thanks for the review, 
I will add an api.xml entry describing the licensePath property in templates in loaders module and integrate later today
Comment 13 Jaroslav Tulach 2013-02-25 15:31:50 UTC
I am not comfortable with any changes related to this issue in loaders. Please delay your integration.
Comment 14 Milos Kleint 2013-02-25 15:36:25 UTC
(In reply to comment #13)
> I am not comfortable with any changes related to this issue in loaders. Please
> delay your integration.

Can you be more specific?
Comment 15 Jaroslav Tulach 2013-02-25 15:39:21 UTC
(In reply to comment #11)
> (In reply to comment #10)
> > Y01 The existing property is defined in projectuiapi/arch.xml. 
> 
> I see, that's why I didn't find it. That's fairly out of place location given
> current behaviour. Neither templates nor the
> CreateFromTemplateAttributesProvider interface are project specific nowadays.

CreateFromTemplateAttributesProvider is indeed generic way for any module in NetBeans to provide additional properties during templates creation. However the project.license value is project specific. And this it was defined by projectuiapi.

True, abstracting away from project, by having licensePath might be considered general enough, still I don't like the idea of defining this in openide.loaders. At the end the only modules that set the property are project based. Keep the "license API" project specific.

> > Y02 Given Y02, I'd suggest to use "project.license.path" property in the > > and describe it in projectuiapi/arch.xml as well
> 
> you mean the "licensePath" template attribute value as included in the
> templates? for the reasons above, I suggest we either move the existing
> template attributes to the loaders or add the new one to loaders and reference
> the pre-existing ones from there.

I guess I don't get the "reasons above". If CreateFromTemplateAttributesProvider is one of such reasons, then I don't agree with the reasoning. CreateFromTemplateAttributesProvider is general API, project.license.path or licensePath should be its project specific implementation.

> I've used a single "word" here because anything separated by a dot ends up
> being nested maps. I assume the original purpose of the dot convention was to
> traverse object trees but we don't have any project instance with license
> property.

We have instances with "wizard" provided properties. Having another namespace for project properties made (and still sort of makes) sense to me.
Comment 16 Milos Kleint 2013-02-25 15:55:57 UTC
(In reply to comment #15)
> (In reply to comment #11)
> > (In reply to comment #10)
> > > Y01 The existing property is defined in projectuiapi/arch.xml. 
> > 
> > I see, that's why I didn't find it. That's fairly out of place location given
> > current behaviour. Neither templates nor the
> > CreateFromTemplateAttributesProvider interface are project specific nowadays.
> 
> CreateFromTemplateAttributesProvider is indeed generic way for any module in
> NetBeans to provide additional properties during templates creation. However
> the project.license value is project specific. And this it was defined by
> projectuiapi.
> 
> True, abstracting away from project, by having licensePath might be considered
> general enough, still I don't like the idea of defining this in
> openide.loaders. At the end the only modules that set the property are project
> based. Keep the "license API" project specific.

Is your objection just targeting the documentation location? I'm a bit confused here. If a template contains the include directive with the licensePath, then it needs to be defined, otherwise the template fails to get processed properly.


> 
> > > Y02 Given Y02, I'd suggest to use "project.license.path" property in the > > and describe it in projectuiapi/arch.xml as well
> > 
> > you mean the "licensePath" template attribute value as included in the
> > templates? for the reasons above, I suggest we either move the existing
> > template attributes to the loaders or add the new one to loaders and reference
> > the pre-existing ones from there.
> 
> I guess I don't get the "reasons above". If
> CreateFromTemplateAttributesProvider is one of such reasons, then I don't agree
> with the reasoning. CreateFromTemplateAttributesProvider is general API,
> project.license.path or licensePath should be its project specific
> implementation.
> 
> > I've used a single "word" here because anything separated by a dot ends up
> > being nested maps. I assume the original purpose of the dot convention was to
> > traverse object trees but we don't have any project instance with license
> > property.
> 
> We have instances with "wizard" provided properties. Having another namespace
> for project properties made (and still sort of makes) sense to me.


having an attribute used in templates is a generic contract between someone who writes the template and someone who provides the attribute values.


But if you are really holding the entire work just because of one line of documentation, I'm going to succumb to your super powers because I don't really care where the documentation noone reads is placed. :)
Comment 17 Jaroslav Tulach 2013-02-25 17:18:08 UTC
I don't want to hold the whole integration, I just don't want to accept contribution to openide.loaders I am not comfortable with.

We can discuss options when you are at work. Meanwhile I talked to Tomáš Zezula. According to him, the Java templates are defined in java.project module. The module has dependency on projectuiapi. I treat this as a supporting argument for documenting the property in projectuiapi/arch.xml. The definition could also say that "all implementations of projects are suggested to make sure the property is defined and modules that want to use the property should have (some for of) dependency on the project (ui) infrastructure" (Y01).

Y04 You are right, the discoverability of the contract is not high, it would be better to have a reference to it from CreateFromTemplateAttributesProvider. Please use <p class="nonnormative"> in its javadoc to refer to <a href="@org-netbeans-modules-projectuiapi@/architecture-overview.html#..."/> specification.

I still believe the prefix "project." would suite the new property more (Y02), but I can give up on that, if I am the only one who sees that such way.

Please give me and others 24h to review the next patch.
Comment 18 Milos Kleint 2013-02-25 17:28:38 UTC
(In reply to comment #17)
> 
> We can discuss options when you are at work. Meanwhile I talked to Tomáš
> Zezula. According to him, the Java templates are defined in java.project
> module. The module has dependency on projectuiapi. I treat this as a supporting
> argument for documenting the property in projectuiapi/arch.xml. The definition
> could also say that "all implementations of projects are suggested to make sure
> the property is defined and modules that want to use the property should have
> (some for of) dependency on the project (ui) infrastructure" (Y01).

There are a lot of templates defined in modules that don't expose any dependencies on the project system, most reference loaders though. Some declare the freemarker requirement, some don't.  The only real dependency is on the Templates/ location in system filesystem. That's the piece of the puzzle that holds the contract together.
Comment 19 Milos Kleint 2013-02-25 21:02:23 UTC
Created attachment 131867 [details]
updated patch to core modules

please see the updated patch, datasystems code is dumped, part of lib.freemarker code is dumped, all is now stuffed into projectui's project implementation of the template attribute provider. and the prop name is project.licensePath
Comment 20 Jaroslav Tulach 2013-02-26 08:55:04 UTC
> There are a lot of templates defined in modules that don't expose any
> dependencies on the project system

I could find for example 
db.core/src/org/netbeans/modules/db/core/resources/SQLTemplate.sql
but in this case it is completely fine, as it does not use project.license at all. It really uses only the "Templates/" contract.

Re. new patch: It seems to use licensePath without prefix in the actual templates (Y02). The prefix is used only in Ant based project.properties as far as I can tell. As mentioned in comment #17 I would prefer the "project." prefix in all cases. 

The property(ies) does not seem to be documented anywhere in the new patch. projectuiapi/arch.xml remains my preferred location for the actual definition (Y01) with a non-normative reference from loaders documentation (Y04). Btw. http://bits.netbeans.org/dev/javadoc/org-openide-loaders/architecture-summary.html#script might be good location to mention the possible existence of your new property.
Comment 21 Milos Kleint 2013-02-26 09:07:34 UTC
(In reply to comment #20)
> > There are a lot of templates defined in modules that don't expose any
> > dependencies on the project system
> 
> I could find for example 
> db.core/src/org/netbeans/modules/db/core/resources/SQLTemplate.sql
> but in this case it is completely fine, as it does not use project.license at
> all. It really uses only the "Templates/" contract.
> 
> Re. new patch: It seems to use licensePath without prefix in the actual
> templates (Y02). The prefix is used only in Ant based project.properties as far
> as I can tell. As mentioned in comment #17 I would prefer the "project." prefix
> in all cases. 

I haven't updated the templates patch, only the code patch but they have now "project.licensePath"


> 
> The property(ies) does not seem to be documented anywhere in the new patch.
> projectuiapi/arch.xml remains my preferred location for the actual definition
> (Y01) with a non-normative reference from loaders documentation (Y04).

Please look again, it's in projectuiapi/arch.xml
Comment 22 Jaroslav Tulach 2013-02-26 12:14:34 UTC
I see. OK, from my point of view. Last note:

Y05 Please provide projectuiapi/apichanges.xml entry so the property appears in what's new list for next version.
Comment 23 Milos Kleint 2013-02-27 11:50:22 UTC
http://hg.netbeans.org/core-main/rev/1dd8792cfa48
Comment 24 Quality Engineering 2013-03-01 02:01:28 UTC
Integrated into 'main-golden', will be available in build *201302282300* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/1dd8792cfa48
User: Milos Kleint <mkleint@netbeans.org>
Log: #193981 change file templates to allow pointing to a license header template stored outside of IDE's system filesystem.


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo