You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by Alex Heneveld <al...@cloudsoftcorp.com> on 2014/09/17 11:17:56 UTC
license headers and config section
Hi folks,
I've prepared a PR #169 which removes the license headers from the YAML
blueprints, as discussed. The reason was that these are used as
examples, often cutting and pasting, and having the license really gets
in the way at runtime. (You can't see the blueprint when you paste the
YAML into the GUI, all you see are the headers!)
I've also remove it from most of the HTML source pages: I don't think
we realized the implication of putting them there -- since most of the
HTML pages are templates, the license header ends up included in the
resulting HTML hundreds of times! This bloats the pages and slows down
processing.
The header is still included in the root index.html which is used for
every page -- so it appears in every page at runtime. It is also in
every CSS and JS, where the optimizer can remove it so there is no
runtime impact.
I think this is the best compromise but of course if there is guidance
to the contrary we can reconsider.
I have also moved the config section to the summary tab, to try that
out. [#168]
Best
Alex
[#169] https://github.com/apache/incubator-brooklyn/pull/169
[#168] https://github.com/apache/incubator-brooklyn/pull/168
Re: license headers and config section
Posted by David Nalley <da...@gnsa.us>.
So in general, citing precedence because a TLP does something won't
help you. TLPs are generally pretty independent, their PMCs get to
make decisions and worst case they have to justify their actions to
the board. Podlings on the other hand, have their releases, especially
their first release, really vetted thoroughly to comply with policy as
its written. In place of a PMC, podlings have the IPMC - which is a
group of 450 people who sit in judgement of your codebase. I don't
mean that to sound harsh, but that's the situation. Demonstrating the
ability to do IP Clearance right is a big deal; and a huge effort. It
can be painful, and annoying; for the first ACS release, we had a
number of config files with no copyright information that we had to
track the original author down for to get an explicit grant; and it
took us weeks to get that sorted to everyone's satisfaction. I said
all of that to say, there are valid reasons to not have a source
header; that $BigTLP does it that way is invariably not one of them.
The Apache brand has a strong reputation for it's clean IP, and decent
record keeping, and some of the rigidity in place is designed to keep
that reputation intact.
--David
On Fri, Sep 19, 2014 at 5:45 AM, Alex Heneveld
<al...@cloudsoftcorp.com> wrote:
>
> Mentors,
>
> I was curious how other projects addressed these problems. It seems that
> what we are seeking to do has precedents by some of the best-known Apache
> projects.
>
> Hadoop, for example, excludes the Apache header in HTML *template* files
> [1].
>
> And Cassandra, for example, excludes the Apache header in YAML files
> intended for end-user consumption (config and examples) [2].
>
> Hopefully this means we can proceed with this?!
>
> As penance I have been extra diligent with our NOTICE file. [4]
>
> Best
> Alex
>
>
> [1]
> https://github.com/apache/hadoop/blob/trunk/hadoop-tools/hadoop-sls/src/main/html/track.html.template
> [2] https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
> [3]
> https://github.com/apache/cassandra/blob/trunk/tools/cqlstress-counter-example.yaml
> [4] https://github.com/apache/incubator-brooklyn/pull/179
>
>
>
> On 19/09/2014 09:03, Alex Heneveld wrote:
>>
>>
>> David- Thanks.
>>
>> Chip, mentors- Appreciate your thoughts.
>>
>>
>> The issue is that many of the HTML files are templates. Many are just
>> one-line. They'll be included hundreds of times, or thousands if it's a big
>> (in-memory) table when pages are rendered. So it has significant
>> performance and memory impact.
>>
>> It is only those templates which have had the header removed. All the
>> base HTML files include the header.
>>
>> I don't know if it makes a difference but these template files are not in
>> the distributables directly (wrt the condition that "human readable files in
>> the distribution); they are only inside the WAR inside the distributable and
>> there is already a LICENSE inside the WAR.
>>
>> Given the above would this be alright? Or if not can you suggest how
>> other projects resolve this?
>>
>> Cheers
>> Alex
>>
>>
>> On 19/09/2014 07:06, David Nalley wrote:
>>>
>>> Hi Alex,
>>>
>>> So expect this to be challenged when your first release hits the IPMC
>>> (or even when mentors are reviewing code)
>>> Specifically, saving space or bandwidth isn't a good justification for
>>> not having a license header; from a policy perspective. There have
>>> been discussions in the past about using a shorter license header -
>>> but I'd argue that it's probably not in the best interest of folks
>>> trying to get a podlings first release out to engage on that issue.
>>>
>>> Chip; or other mentors - anyone feel I am off base here?
>>>
>>> --David
>>>
>>> On Wed, Sep 17, 2014 at 5:17 AM, Alex Heneveld
>>> <al...@cloudsoftcorp.com> wrote:
>>>>
>>>> Hi folks,
>>>>
>>>> I've prepared a PR #169 which removes the license headers from the YAML
>>>> blueprints, as discussed. The reason was that these are used as
>>>> examples,
>>>> often cutting and pasting, and having the license really gets in the way
>>>> at
>>>> runtime. (You can't see the blueprint when you paste the YAML into the
>>>> GUI,
>>>> all you see are the headers!)
>>>>
>>>> I've also remove it from most of the HTML source pages: I don't think
>>>> we
>>>> realized the implication of putting them there -- since most of the HTML
>>>> pages are templates, the license header ends up included in the
>>>> resulting
>>>> HTML hundreds of times! This bloats the pages and slows down
>>>> processing.
>>>>
>>>> The header is still included in the root index.html which is used for
>>>> every
>>>> page -- so it appears in every page at runtime. It is also in every CSS
>>>> and
>>>> JS, where the optimizer can remove it so there is no runtime impact.
>>>>
>>>> I think this is the best compromise but of course if there is guidance
>>>> to
>>>> the contrary we can reconsider.
>>>>
>>>> I have also moved the config section to the summary tab, to try that
>>>> out.
>>>> [#168]
>>>>
>>>> Best
>>>> Alex
>>>>
>>>>
>>>> [#169] https://github.com/apache/incubator-brooklyn/pull/169
>>>> [#168] https://github.com/apache/incubator-brooklyn/pull/168
>>
>>
>
Re: license headers and config section
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
Mentors,
I was curious how other projects addressed these problems. It seems
that what we are seeking to do has precedents by some of the best-known
Apache projects.
Hadoop, for example, excludes the Apache header in HTML *template* files
[1].
And Cassandra, for example, excludes the Apache header in YAML files
intended for end-user consumption (config and examples) [2].
Hopefully this means we can proceed with this?!
As penance I have been extra diligent with our NOTICE file. [4]
Best
Alex
[1]
https://github.com/apache/hadoop/blob/trunk/hadoop-tools/hadoop-sls/src/main/html/track.html.template
[2] https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
[3]
https://github.com/apache/cassandra/blob/trunk/tools/cqlstress-counter-example.yaml
[4] https://github.com/apache/incubator-brooklyn/pull/179
On 19/09/2014 09:03, Alex Heneveld wrote:
>
> David- Thanks.
>
> Chip, mentors- Appreciate your thoughts.
>
>
> The issue is that many of the HTML files are templates. Many are just
> one-line. They'll be included hundreds of times, or thousands if it's
> a big (in-memory) table when pages are rendered. So it has
> significant performance and memory impact.
>
> It is only those templates which have had the header removed. All the
> base HTML files include the header.
>
> I don't know if it makes a difference but these template files are not
> in the distributables directly (wrt the condition that "human readable
> files in the distribution); they are only inside the WAR inside the
> distributable and there is already a LICENSE inside the WAR.
>
> Given the above would this be alright? Or if not can you suggest how
> other projects resolve this?
>
> Cheers
> Alex
>
>
> On 19/09/2014 07:06, David Nalley wrote:
>> Hi Alex,
>>
>> So expect this to be challenged when your first release hits the IPMC
>> (or even when mentors are reviewing code)
>> Specifically, saving space or bandwidth isn't a good justification for
>> not having a license header; from a policy perspective. There have
>> been discussions in the past about using a shorter license header -
>> but I'd argue that it's probably not in the best interest of folks
>> trying to get a podlings first release out to engage on that issue.
>>
>> Chip; or other mentors - anyone feel I am off base here?
>>
>> --David
>>
>> On Wed, Sep 17, 2014 at 5:17 AM, Alex Heneveld
>> <al...@cloudsoftcorp.com> wrote:
>>> Hi folks,
>>>
>>> I've prepared a PR #169 which removes the license headers from the YAML
>>> blueprints, as discussed. The reason was that these are used as
>>> examples,
>>> often cutting and pasting, and having the license really gets in the
>>> way at
>>> runtime. (You can't see the blueprint when you paste the YAML into
>>> the GUI,
>>> all you see are the headers!)
>>>
>>> I've also remove it from most of the HTML source pages: I don't
>>> think we
>>> realized the implication of putting them there -- since most of the
>>> HTML
>>> pages are templates, the license header ends up included in the
>>> resulting
>>> HTML hundreds of times! This bloats the pages and slows down
>>> processing.
>>>
>>> The header is still included in the root index.html which is used
>>> for every
>>> page -- so it appears in every page at runtime. It is also in every
>>> CSS and
>>> JS, where the optimizer can remove it so there is no runtime impact.
>>>
>>> I think this is the best compromise but of course if there is
>>> guidance to
>>> the contrary we can reconsider.
>>>
>>> I have also moved the config section to the summary tab, to try that
>>> out.
>>> [#168]
>>>
>>> Best
>>> Alex
>>>
>>>
>>> [#169] https://github.com/apache/incubator-brooklyn/pull/169
>>> [#168] https://github.com/apache/incubator-brooklyn/pull/168
>
Re: license headers and config section
Posted by Andrew Kennedy <an...@cloudsoftcorp.com>.
OK, understood, that makes sense for our console UI HTML, I wasn't
thinking about that.
Andrew.
--
-- andrew kennedy ? cloud engineer : http://blog.abstractvisitorpattern.co.uk/ ;
On 22 September 2014 10:04, Alex Heneveld
<al...@cloudsoftcorp.com> wrote:
>
> Hi Andrew,
>
> This is the in-product dashboard, where the template HTML files are included
> in a release (albeit in a WAR file). They will also be included in a source
> release which I think we should be making, so I think it doesn't matter that
> they are in a WAR file in the binary release.
>
> --A
>
>
>
> On 22/09/2014 09:59, Andrew Kennedy wrote:
>
> On 22 September 2014 09:30, Alex Heneveld <al...@cloudsoftcorp.com>
> wrote:
>> (5) Template HTML - these ARE included in the releases and DO have
>> creativity, much of them, so it sounds like they MUST have licenses. This
>> is the resolution I'm least pleased with due to the performance hit but I
>> guess we have to take that. Maybe we could in time write a variant of
>> _.template which filters comments (since templates are always being
>> included in pages which already have a license). KEEP HEADERS.
>
> Are these going to be in a release? According to David "The source header
> policy only applies to software that we release. It does not apply to
> websites." So we should be OK removing the license details here, for
> documentation that goes on the website only, which is what we intend to do
> with the content of 'docs/' currently.
>
> David - what about documentation templates and files that are used to
> generate a final rendered document that *is* released? Would they then be
> counted as source, in which case Alex's statement above holds?
>
> Cheers,
> Andrew.
> --
> -- andrew kennedy ? cloud engineer :
> http://blog.abstractvisitorpattern.co.uk/ ;
>
>
Re: license headers and config section
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
David- Thanks for your continued guidance here and the explanations.
All-
Here is my understanding of the areas where we still need to resolve
headers, and a proposed resolution for each:
(1) Example Java and YAML in test/resources and docs - these are NOT
included in the releases (they are mainly in tests) and more to the
point they do NOT have creativity; they are just obvious demonstrations
of how the corresponding entities can be used and configured. REMOVE
HEADERS on basis of the exemption.
(2) Example Java and YAML in example projects - these probably DO need
headers as they are distributed; an argument could perhaps be made about
no creativity but I don't think it's worth it as headers here seem least
likely to cause problems. KEEP HEADERS.
(3) Java and YAML in the archetype used for new projects - these do NOT
show creativity, and including the license header is disruptive to
users. REMOVE HEADERS here on basis of the exemption.
(4) Third-party YAML and XML (eg config such as cassandra.yaml) - as I
understand it we do NOT have the right to add the license here; we DO
need to properly attribute them. I think we should put a short comment
describing the origin of these files and a summary of changes. EDIT as
appropriate.
(5) Template HTML - these ARE included in the releases and DO have
creativity, much of them, so it sounds like they MUST have licenses.
This is the resolution I'm least pleased with due to the performance hit
but I guess we have to take that. Maybe we could in time write a
variant of _.template which filters comments (since templates are always
being included in pages which already have a license). KEEP HEADERS.
Does this sound right?
Best
Alex
On 22/09/2014 05:45, David Nalley wrote:
> More inline responses.
>
> --David
>
> On Sat, Sep 20, 2014 at 6:09 AM, Aled Sage <al...@cloudsoftcorp.com> wrote:
>> Thanks, very useful comments. Responses in-line.
>>
>>
>> On 20/09/2014 03:35, David Nalley wrote:
>>> On Fri, Sep 19, 2014 at 5:48 AM, Aled Sage <al...@cloudsoftcorp.com>
>>> wrote:
>>>> Hi all,
>>>>
>>>> Some of these files are more controversial than others. Let's break it
>>>> down...
>>>>
>>> I think this is the right approach; this is essentially what you
>>> should be prepared to do when it gets to the IPMC.
>>>
>>>> For YAML files, there are a few categories:
>>>>
>>>> 1. Files inside docs (e.g. [1]). The contents of these files normally
>>>> get embedded inside an html page as a code-block example. Including
>>>> the header in every embedded example makes the resulting web-page
>>>> harder to read.
>>> I don't think that harder to read is a good reason. However, my
>>> question to you would be; are the docs going to be part of your
>>> release, or just something that you publish to the website. Keep in
>>> mind that the entire repository might not be what is in a release.
>>>
>>> But; if you read the page for this policy there is an exception:
>>> http://www.apache.org/legal/src-headers.html#faq-exceptions
>>>
>>> Is there any creativity in this list of key-value constructs? I'd
>>> argue that example 1 has no creativity. It is merely a factual listing
>>> of keys and values. E.g. my personal opinion is that if [1] is
>>> representative of all of this class of file then I'd argue there is no
>>> creativity and no header is needed.
>> [ALED] The docs are just for the website (not included in the release), so I
>> believe that means we can safely delete the headers.
>>
>> By "harder to read", I meant for someone reading the generated documentation
>> - and thus directly affects the quality of the documentation.
>>
> The source header policy only applies to software that we release. It
> does not apply to websites or non-released (for very specific
> definitions of released, in an ASF context) artifacts.
>
>>>> 2. Files in the examples. We expect some people to copy-paste these as
>>>> the basis for their own applications.
>>> This is almost certainly not a reason to remove the license header.
>>>
>>>> 3. Test files (in src/test/resources)
>>>>
>>> What is the impact on the test. In example, jclouds as a podling,
>>> discovered that the license header in test response files made tests
>>> fail.
>>>
>>>> For (1), I strongly believe it should not include the headers.
>>>>
>>>> For (2) and (3), I'll abstain.
>>>>
>>>> ---
>>>> There are also files inside the maven archetype. These are used to
>>>> generate
>>>> a maven project with starter classes + scripts.
>>>>
>>>> I expect the first thing almost all users of this archetype will do is to
>>>> delete the copyright header from every file they modify, because their
>>>> downstream may not be apache licensed.
>>>>
>>>> Can we exclude the headers there?
>>>>
>>> So I read what you wrote as what people will do (though removing our
>>> notice would violate the terms of the license). What I didn't see was
>>> how you plan to justify exclusion of the license headers in the scope
>>> of the policy. I'd guess the answer is no here.
>> [ALED] Do I understand you correctly that anyone creating a downstream
>> project using the maven archetype should *not* remove the headers, even
>> though we expect such users to substantially change the contents of the
>> files?
>>
>> Perhaps I didn't explain clearly: the maven archetype copies resources into
>> the structure for a new maven project. This gives someone a starting point
>> for them to write their own application blueprints. For example, it gives a
>> starting pom.xml file with a dependency on brooklyn - we expect users to
>> then add dependencies for everything else they need. Same for the Java code
>> - it just gives a basic template.
>>
> It sounds like what you are saying is that there is no creative
> content in the archetype. If that is the case, it would qualify for
> the exception to the license header policy.
>
>> I presume the code the user adds to these files would not be copyright of
>> apache, so I'd have expected the user to want to remove the headers. It
>> feels wrong to me to include the headers at all in these template files.
>>
>>>> ---
>>>> We have config files for the software installed by Brooklyn (e.g. [2]).
>>>> These are often the standard configuration file that comes with the given
>>>> software (e.g. with Cassandra), but templated (using freemarker) so we
>>>> can
>>>> easily substitute various configuration options. A user can copy this
>>>> file
>>>> to tweak the configuration for their own installs.
>>>>
>>> Where did you get the configuration file from? If it came from a third
>>> party, you can't add a license header - the license header policy only
>>> covers code developed at the ASF or granted to the ASF as part of a
>>> SGA or CCLA.
>> [ALED] Thanks, makes sense.
>>
>>>> Should we really claim apache license on that, by including the header?
>>>>
>>>> Also note that apache cassandra (where the file came from) does not have
>>>> the
>>>> header in this file, presumably because it is expected to be modified by
>>>> the
>>>> end user:
>>>> https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
>>>>
>>> If it's third party (even if that third party is another ASF project)
>>> you should assume that you don't have the rights to change it.
>>>
Re: license headers and config section
Posted by David Nalley <da...@gnsa.us>.
More inline responses.
--David
On Sat, Sep 20, 2014 at 6:09 AM, Aled Sage <al...@cloudsoftcorp.com> wrote:
> Thanks, very useful comments. Responses in-line.
>
>
> On 20/09/2014 03:35, David Nalley wrote:
>>
>> On Fri, Sep 19, 2014 at 5:48 AM, Aled Sage <al...@cloudsoftcorp.com>
>> wrote:
>>>
>>> Hi all,
>>>
>>> Some of these files are more controversial than others. Let's break it
>>> down...
>>>
>> I think this is the right approach; this is essentially what you
>> should be prepared to do when it gets to the IPMC.
>>
>>> For YAML files, there are a few categories:
>>>
>>> 1. Files inside docs (e.g. [1]). The contents of these files normally
>>> get embedded inside an html page as a code-block example. Including
>>> the header in every embedded example makes the resulting web-page
>>> harder to read.
>>
>> I don't think that harder to read is a good reason. However, my
>> question to you would be; are the docs going to be part of your
>> release, or just something that you publish to the website. Keep in
>> mind that the entire repository might not be what is in a release.
>>
>> But; if you read the page for this policy there is an exception:
>> http://www.apache.org/legal/src-headers.html#faq-exceptions
>>
>> Is there any creativity in this list of key-value constructs? I'd
>> argue that example 1 has no creativity. It is merely a factual listing
>> of keys and values. E.g. my personal opinion is that if [1] is
>> representative of all of this class of file then I'd argue there is no
>> creativity and no header is needed.
>
> [ALED] The docs are just for the website (not included in the release), so I
> believe that means we can safely delete the headers.
>
> By "harder to read", I meant for someone reading the generated documentation
> - and thus directly affects the quality of the documentation.
>
The source header policy only applies to software that we release. It
does not apply to websites or non-released (for very specific
definitions of released, in an ASF context) artifacts.
>>> 2. Files in the examples. We expect some people to copy-paste these as
>>> the basis for their own applications.
>>
>> This is almost certainly not a reason to remove the license header.
>>
>>> 3. Test files (in src/test/resources)
>>>
>> What is the impact on the test. In example, jclouds as a podling,
>> discovered that the license header in test response files made tests
>> fail.
>>
>>> For (1), I strongly believe it should not include the headers.
>>>
>>> For (2) and (3), I'll abstain.
>>>
>>> ---
>>> There are also files inside the maven archetype. These are used to
>>> generate
>>> a maven project with starter classes + scripts.
>>>
>>> I expect the first thing almost all users of this archetype will do is to
>>> delete the copyright header from every file they modify, because their
>>> downstream may not be apache licensed.
>>>
>>> Can we exclude the headers there?
>>>
>> So I read what you wrote as what people will do (though removing our
>> notice would violate the terms of the license). What I didn't see was
>> how you plan to justify exclusion of the license headers in the scope
>> of the policy. I'd guess the answer is no here.
>
> [ALED] Do I understand you correctly that anyone creating a downstream
> project using the maven archetype should *not* remove the headers, even
> though we expect such users to substantially change the contents of the
> files?
>
> Perhaps I didn't explain clearly: the maven archetype copies resources into
> the structure for a new maven project. This gives someone a starting point
> for them to write their own application blueprints. For example, it gives a
> starting pom.xml file with a dependency on brooklyn - we expect users to
> then add dependencies for everything else they need. Same for the Java code
> - it just gives a basic template.
>
It sounds like what you are saying is that there is no creative
content in the archetype. If that is the case, it would qualify for
the exception to the license header policy.
> I presume the code the user adds to these files would not be copyright of
> apache, so I'd have expected the user to want to remove the headers. It
> feels wrong to me to include the headers at all in these template files.
>
>>> ---
>>> We have config files for the software installed by Brooklyn (e.g. [2]).
>>> These are often the standard configuration file that comes with the given
>>> software (e.g. with Cassandra), but templated (using freemarker) so we
>>> can
>>> easily substitute various configuration options. A user can copy this
>>> file
>>> to tweak the configuration for their own installs.
>>>
>> Where did you get the configuration file from? If it came from a third
>> party, you can't add a license header - the license header policy only
>> covers code developed at the ASF or granted to the ASF as part of a
>> SGA or CCLA.
>
> [ALED] Thanks, makes sense.
>
>>
>>> Should we really claim apache license on that, by including the header?
>>>
>>> Also note that apache cassandra (where the file came from) does not have
>>> the
>>> header in this file, presumably because it is expected to be modified by
>>> the
>>> end user:
>>> https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
>>>
>> If it's third party (even if that third party is another ASF project)
>> you should assume that you don't have the rights to change it.
>>
>
Re: license headers and config section
Posted by Aled Sage <al...@cloudsoftcorp.com>.
Thanks, very useful comments. Responses in-line.
On 20/09/2014 03:35, David Nalley wrote:
> On Fri, Sep 19, 2014 at 5:48 AM, Aled Sage <al...@cloudsoftcorp.com> wrote:
>> Hi all,
>>
>> Some of these files are more controversial than others. Let's break it
>> down...
>>
> I think this is the right approach; this is essentially what you
> should be prepared to do when it gets to the IPMC.
>
>> For YAML files, there are a few categories:
>>
>> 1. Files inside docs (e.g. [1]). The contents of these files normally
>> get embedded inside an html page as a code-block example. Including
>> the header in every embedded example makes the resulting web-page
>> harder to read.
> I don't think that harder to read is a good reason. However, my
> question to you would be; are the docs going to be part of your
> release, or just something that you publish to the website. Keep in
> mind that the entire repository might not be what is in a release.
>
> But; if you read the page for this policy there is an exception:
> http://www.apache.org/legal/src-headers.html#faq-exceptions
>
> Is there any creativity in this list of key-value constructs? I'd
> argue that example 1 has no creativity. It is merely a factual listing
> of keys and values. E.g. my personal opinion is that if [1] is
> representative of all of this class of file then I'd argue there is no
> creativity and no header is needed.
[ALED] The docs are just for the website (not included in the release),
so I believe that means we can safely delete the headers.
By "harder to read", I meant for someone reading the generated
documentation - and thus directly affects the quality of the documentation.
>> 2. Files in the examples. We expect some people to copy-paste these as
>> the basis for their own applications.
> This is almost certainly not a reason to remove the license header.
>
>> 3. Test files (in src/test/resources)
>>
> What is the impact on the test. In example, jclouds as a podling,
> discovered that the license header in test response files made tests
> fail.
>
>> For (1), I strongly believe it should not include the headers.
>>
>> For (2) and (3), I'll abstain.
>>
>> ---
>> There are also files inside the maven archetype. These are used to generate
>> a maven project with starter classes + scripts.
>>
>> I expect the first thing almost all users of this archetype will do is to
>> delete the copyright header from every file they modify, because their
>> downstream may not be apache licensed.
>>
>> Can we exclude the headers there?
>>
> So I read what you wrote as what people will do (though removing our
> notice would violate the terms of the license). What I didn't see was
> how you plan to justify exclusion of the license headers in the scope
> of the policy. I'd guess the answer is no here.
[ALED] Do I understand you correctly that anyone creating a downstream
project using the maven archetype should *not* remove the headers, even
though we expect such users to substantially change the contents of the
files?
Perhaps I didn't explain clearly: the maven archetype copies resources
into the structure for a new maven project. This gives someone a
starting point for them to write their own application blueprints. For
example, it gives a starting pom.xml file with a dependency on brooklyn
- we expect users to then add dependencies for everything else they
need. Same for the Java code - it just gives a basic template.
I presume the code the user adds to these files would not be copyright
of apache, so I'd have expected the user to want to remove the headers.
It feels wrong to me to include the headers at all in these template files.
>> ---
>> We have config files for the software installed by Brooklyn (e.g. [2]).
>> These are often the standard configuration file that comes with the given
>> software (e.g. with Cassandra), but templated (using freemarker) so we can
>> easily substitute various configuration options. A user can copy this file
>> to tweak the configuration for their own installs.
>>
> Where did you get the configuration file from? If it came from a third
> party, you can't add a license header - the license header policy only
> covers code developed at the ASF or granted to the ASF as part of a
> SGA or CCLA.
[ALED] Thanks, makes sense.
>
>> Should we really claim apache license on that, by including the header?
>>
>> Also note that apache cassandra (where the file came from) does not have the
>> header in this file, presumably because it is expected to be modified by the
>> end user:
>> https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
>>
> If it's third party (even if that third party is another ASF project)
> you should assume that you don't have the rights to change it.
>
Re: license headers and config section
Posted by David Nalley <da...@gnsa.us>.
On Fri, Sep 19, 2014 at 5:48 AM, Aled Sage <al...@cloudsoftcorp.com> wrote:
> Hi all,
>
> Some of these files are more controversial than others. Let's break it
> down...
>
I think this is the right approach; this is essentially what you
should be prepared to do when it gets to the IPMC.
> For YAML files, there are a few categories:
>
> 1. Files inside docs (e.g. [1]). The contents of these files normally
> get embedded inside an html page as a code-block example. Including
> the header in every embedded example makes the resulting web-page
> harder to read.
I don't think that harder to read is a good reason. However, my
question to you would be; are the docs going to be part of your
release, or just something that you publish to the website. Keep in
mind that the entire repository might not be what is in a release.
But; if you read the page for this policy there is an exception:
http://www.apache.org/legal/src-headers.html#faq-exceptions
Is there any creativity in this list of key-value constructs? I'd
argue that example 1 has no creativity. It is merely a factual listing
of keys and values. E.g. my personal opinion is that if [1] is
representative of all of this class of file then I'd argue there is no
creativity and no header is needed.
> 2. Files in the examples. We expect some people to copy-paste these as
> the basis for their own applications.
This is almost certainly not a reason to remove the license header.
> 3. Test files (in src/test/resources)
>
What is the impact on the test. In example, jclouds as a podling,
discovered that the license header in test response files made tests
fail.
> For (1), I strongly believe it should not include the headers.
>
> For (2) and (3), I'll abstain.
>
> ---
> There are also files inside the maven archetype. These are used to generate
> a maven project with starter classes + scripts.
>
> I expect the first thing almost all users of this archetype will do is to
> delete the copyright header from every file they modify, because their
> downstream may not be apache licensed.
>
> Can we exclude the headers there?
>
So I read what you wrote as what people will do (though removing our
notice would violate the terms of the license). What I didn't see was
how you plan to justify exclusion of the license headers in the scope
of the policy. I'd guess the answer is no here.
> ---
> We have config files for the software installed by Brooklyn (e.g. [2]).
> These are often the standard configuration file that comes with the given
> software (e.g. with Cassandra), but templated (using freemarker) so we can
> easily substitute various configuration options. A user can copy this file
> to tweak the configuration for their own installs.
>
Where did you get the configuration file from? If it came from a third
party, you can't add a license header - the license header policy only
covers code developed at the ASF or granted to the ASF as part of a
SGA or CCLA.
> Should we really claim apache license on that, by including the header?
>
> Also note that apache cassandra (where the file came from) does not have the
> header in this file, presumably because it is expected to be modified by the
> end user:
> https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
>
If it's third party (even if that third party is another ASF project)
you should assume that you don't have the rights to change it.
> Interesting they also don't include it in the test configuration file, which
> presumably no user should be modifying.
> https://github.com/apache/cassandra/blob/trunk/test/conf/cassandra.yaml
>
> Aled
>
> p.s. double-checking what some other apache projects do, surprised to see
> wording like "WSO2 Inc. licenses this file to you under the Apache License"
> [3]!
So that's a third-party dependency. The ASF has no claim to that file
itself, and WSO2 holds the copyright and deals with the license
header. We aren't authorized to change that, and it would be a mistake
to do so. That doesn't mean that Stratos or any other project is
perfect - as a matter of fact, that's worth creating a patch for the
missing notice in the NOTICE file.
>
> [1]
> https://github.com/apache/incubator-brooklyn/blob/master/docs/use/guide/defining-applications/example_yaml/simple-vm.yaml
> [2]
> https://github.com/apache/incubator-brooklyn/blob/master/software/nosql/src/main/resources/brooklyn/entity/nosql/cassandra/cassandra-2.0.yaml
> [3]
> https://github.com/apache/stratos/blob/master/dependencies/org.wso2.carbon.ui/src/main/resources/web/docs/about.html
>
>
> On 19/09/2014 09:03, Alex Heneveld wrote:
>>
>>
>> David- Thanks.
>>
>> Chip, mentors- Appreciate your thoughts.
>>
>>
>> The issue is that many of the HTML files are templates. Many are just
>> one-line. They'll be included hundreds of times, or thousands if it's a big
>> (in-memory) table when pages are rendered. So it has significant
>> performance and memory impact.
>>
>> It is only those templates which have had the header removed. All the
>> base HTML files include the header.
>>
>> I don't know if it makes a difference but these template files are not in
>> the distributables directly (wrt the condition that "human readable files in
>> the distribution); they are only inside the WAR inside the distributable and
>> there is already a LICENSE inside the WAR.
>>
>> Given the above would this be alright? Or if not can you suggest how
>> other projects resolve this?
>>
>> Cheers
>> Alex
>>
>>
>> On 19/09/2014 07:06, David Nalley wrote:
>>>
>>> Hi Alex,
>>>
>>> So expect this to be challenged when your first release hits the IPMC
>>> (or even when mentors are reviewing code)
>>> Specifically, saving space or bandwidth isn't a good justification for
>>> not having a license header; from a policy perspective. There have
>>> been discussions in the past about using a shorter license header -
>>> but I'd argue that it's probably not in the best interest of folks
>>> trying to get a podlings first release out to engage on that issue.
>>>
>>> Chip; or other mentors - anyone feel I am off base here?
>>>
>>> --David
>>>
>>> On Wed, Sep 17, 2014 at 5:17 AM, Alex Heneveld
>>> <al...@cloudsoftcorp.com> wrote:
>>>>
>>>> Hi folks,
>>>>
>>>> I've prepared a PR #169 which removes the license headers from the YAML
>>>> blueprints, as discussed. The reason was that these are used as
>>>> examples,
>>>> often cutting and pasting, and having the license really gets in the way
>>>> at
>>>> runtime. (You can't see the blueprint when you paste the YAML into the
>>>> GUI,
>>>> all you see are the headers!)
>>>>
>>>> I've also remove it from most of the HTML source pages: I don't think
>>>> we
>>>> realized the implication of putting them there -- since most of the HTML
>>>> pages are templates, the license header ends up included in the
>>>> resulting
>>>> HTML hundreds of times! This bloats the pages and slows down
>>>> processing.
>>>>
>>>> The header is still included in the root index.html which is used for
>>>> every
>>>> page -- so it appears in every page at runtime. It is also in every CSS
>>>> and
>>>> JS, where the optimizer can remove it so there is no runtime impact.
>>>>
>>>> I think this is the best compromise but of course if there is guidance
>>>> to
>>>> the contrary we can reconsider.
>>>>
>>>> I have also moved the config section to the summary tab, to try that
>>>> out.
>>>> [#168]
>>>>
>>>> Best
>>>> Alex
>>>>
>>>>
>>>> [#169] https://github.com/apache/incubator-brooklyn/pull/169
>>>> [#168] https://github.com/apache/incubator-brooklyn/pull/168
>>
>>
>
Re: license headers and config section
Posted by Aled Sage <al...@cloudsoftcorp.com>.
Hi all,
Some of these files are more controversial than others. Let's break it
down...
For YAML files, there are a few categories:
1. Files inside docs (e.g. [1]). The contents of these files normally
get embedded inside an html page as a code-block example. Including
the header in every embedded example makes the resulting web-page
harder to read.
2. Files in the examples. We expect some people to copy-paste these as
the basis for their own applications.
3. Test files (in src/test/resources)
For (1), I strongly believe it should not include the headers.
For (2) and (3), I'll abstain.
---
There are also files inside the maven archetype. These are used to
generate a maven project with starter classes + scripts.
I expect the first thing almost all users of this archetype will do is
to delete the copyright header from every file they modify, because
their downstream may not be apache licensed.
Can we exclude the headers there?
---
We have config files for the software installed by Brooklyn (e.g. [2]).
These are often the standard configuration file that comes with the
given software (e.g. with Cassandra), but templated (using freemarker)
so we can easily substitute various configuration options. A user can
copy this file to tweak the configuration for their own installs.
Should we really claim apache license on that, by including the header?
Also note that apache cassandra (where the file came from) does not have
the header in this file, presumably because it is expected to be
modified by the end user:
https://github.com/apache/cassandra/blob/trunk/conf/cassandra.yaml
Interesting they also don't include it in the test configuration file,
which presumably no user should be modifying.
https://github.com/apache/cassandra/blob/trunk/test/conf/cassandra.yaml
Aled
p.s. double-checking what some other apache projects do, surprised to
see wording like "WSO2 Inc. licenses this file to you under the Apache
License" [3]!
[1]
https://github.com/apache/incubator-brooklyn/blob/master/docs/use/guide/defining-applications/example_yaml/simple-vm.yaml
[2]
https://github.com/apache/incubator-brooklyn/blob/master/software/nosql/src/main/resources/brooklyn/entity/nosql/cassandra/cassandra-2.0.yaml
[3]
https://github.com/apache/stratos/blob/master/dependencies/org.wso2.carbon.ui/src/main/resources/web/docs/about.html
On 19/09/2014 09:03, Alex Heneveld wrote:
>
> David- Thanks.
>
> Chip, mentors- Appreciate your thoughts.
>
>
> The issue is that many of the HTML files are templates. Many are just
> one-line. They'll be included hundreds of times, or thousands if it's
> a big (in-memory) table when pages are rendered. So it has
> significant performance and memory impact.
>
> It is only those templates which have had the header removed. All the
> base HTML files include the header.
>
> I don't know if it makes a difference but these template files are not
> in the distributables directly (wrt the condition that "human readable
> files in the distribution); they are only inside the WAR inside the
> distributable and there is already a LICENSE inside the WAR.
>
> Given the above would this be alright? Or if not can you suggest how
> other projects resolve this?
>
> Cheers
> Alex
>
>
> On 19/09/2014 07:06, David Nalley wrote:
>> Hi Alex,
>>
>> So expect this to be challenged when your first release hits the IPMC
>> (or even when mentors are reviewing code)
>> Specifically, saving space or bandwidth isn't a good justification for
>> not having a license header; from a policy perspective. There have
>> been discussions in the past about using a shorter license header -
>> but I'd argue that it's probably not in the best interest of folks
>> trying to get a podlings first release out to engage on that issue.
>>
>> Chip; or other mentors - anyone feel I am off base here?
>>
>> --David
>>
>> On Wed, Sep 17, 2014 at 5:17 AM, Alex Heneveld
>> <al...@cloudsoftcorp.com> wrote:
>>> Hi folks,
>>>
>>> I've prepared a PR #169 which removes the license headers from the YAML
>>> blueprints, as discussed. The reason was that these are used as
>>> examples,
>>> often cutting and pasting, and having the license really gets in the
>>> way at
>>> runtime. (You can't see the blueprint when you paste the YAML into
>>> the GUI,
>>> all you see are the headers!)
>>>
>>> I've also remove it from most of the HTML source pages: I don't
>>> think we
>>> realized the implication of putting them there -- since most of the
>>> HTML
>>> pages are templates, the license header ends up included in the
>>> resulting
>>> HTML hundreds of times! This bloats the pages and slows down
>>> processing.
>>>
>>> The header is still included in the root index.html which is used
>>> for every
>>> page -- so it appears in every page at runtime. It is also in every
>>> CSS and
>>> JS, where the optimizer can remove it so there is no runtime impact.
>>>
>>> I think this is the best compromise but of course if there is
>>> guidance to
>>> the contrary we can reconsider.
>>>
>>> I have also moved the config section to the summary tab, to try that
>>> out.
>>> [#168]
>>>
>>> Best
>>> Alex
>>>
>>>
>>> [#169] https://github.com/apache/incubator-brooklyn/pull/169
>>> [#168] https://github.com/apache/incubator-brooklyn/pull/168
>
Re: license headers and config section
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
David- Thanks.
Chip, mentors- Appreciate your thoughts.
The issue is that many of the HTML files are templates. Many are just
one-line. They'll be included hundreds of times, or thousands if it's a
big (in-memory) table when pages are rendered. So it has significant
performance and memory impact.
It is only those templates which have had the header removed. All the
base HTML files include the header.
I don't know if it makes a difference but these template files are not
in the distributables directly (wrt the condition that "human readable
files in the distribution); they are only inside the WAR inside the
distributable and there is already a LICENSE inside the WAR.
Given the above would this be alright? Or if not can you suggest how
other projects resolve this?
Cheers
Alex
On 19/09/2014 07:06, David Nalley wrote:
> Hi Alex,
>
> So expect this to be challenged when your first release hits the IPMC
> (or even when mentors are reviewing code)
> Specifically, saving space or bandwidth isn't a good justification for
> not having a license header; from a policy perspective. There have
> been discussions in the past about using a shorter license header -
> but I'd argue that it's probably not in the best interest of folks
> trying to get a podlings first release out to engage on that issue.
>
> Chip; or other mentors - anyone feel I am off base here?
>
> --David
>
> On Wed, Sep 17, 2014 at 5:17 AM, Alex Heneveld
> <al...@cloudsoftcorp.com> wrote:
>> Hi folks,
>>
>> I've prepared a PR #169 which removes the license headers from the YAML
>> blueprints, as discussed. The reason was that these are used as examples,
>> often cutting and pasting, and having the license really gets in the way at
>> runtime. (You can't see the blueprint when you paste the YAML into the GUI,
>> all you see are the headers!)
>>
>> I've also remove it from most of the HTML source pages: I don't think we
>> realized the implication of putting them there -- since most of the HTML
>> pages are templates, the license header ends up included in the resulting
>> HTML hundreds of times! This bloats the pages and slows down processing.
>>
>> The header is still included in the root index.html which is used for every
>> page -- so it appears in every page at runtime. It is also in every CSS and
>> JS, where the optimizer can remove it so there is no runtime impact.
>>
>> I think this is the best compromise but of course if there is guidance to
>> the contrary we can reconsider.
>>
>> I have also moved the config section to the summary tab, to try that out.
>> [#168]
>>
>> Best
>> Alex
>>
>>
>> [#169] https://github.com/apache/incubator-brooklyn/pull/169
>> [#168] https://github.com/apache/incubator-brooklyn/pull/168
Re: license headers and config section
Posted by David Nalley <da...@gnsa.us>.
Hi Alex,
So expect this to be challenged when your first release hits the IPMC
(or even when mentors are reviewing code)
Specifically, saving space or bandwidth isn't a good justification for
not having a license header; from a policy perspective. There have
been discussions in the past about using a shorter license header -
but I'd argue that it's probably not in the best interest of folks
trying to get a podlings first release out to engage on that issue.
Chip; or other mentors - anyone feel I am off base here?
--David
On Wed, Sep 17, 2014 at 5:17 AM, Alex Heneveld
<al...@cloudsoftcorp.com> wrote:
> Hi folks,
>
> I've prepared a PR #169 which removes the license headers from the YAML
> blueprints, as discussed. The reason was that these are used as examples,
> often cutting and pasting, and having the license really gets in the way at
> runtime. (You can't see the blueprint when you paste the YAML into the GUI,
> all you see are the headers!)
>
> I've also remove it from most of the HTML source pages: I don't think we
> realized the implication of putting them there -- since most of the HTML
> pages are templates, the license header ends up included in the resulting
> HTML hundreds of times! This bloats the pages and slows down processing.
>
> The header is still included in the root index.html which is used for every
> page -- so it appears in every page at runtime. It is also in every CSS and
> JS, where the optimizer can remove it so there is no runtime impact.
>
> I think this is the best compromise but of course if there is guidance to
> the contrary we can reconsider.
>
> I have also moved the config section to the summary tab, to try that out.
> [#168]
>
> Best
> Alex
>
>
> [#169] https://github.com/apache/incubator-brooklyn/pull/169
> [#168] https://github.com/apache/incubator-brooklyn/pull/168