Adding license headers for *.vm files

Development
#1

Hi devs,

We’re missing license headers for our *.vm files. I’m proposing to use the following format:

#*
# ---------------------------------------------------------------------------
# See the NOTICE file distributed with this work for additional
# information regarding copyright ownership.
#
# This is free software; you can redistribute it and/or modify it
# under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation; either version 2.1 of
# the License, or (at your option) any later version.
#
# This software is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this software; if not, write to the Free
# Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
# 02110-1301 USA, or see the FSF site: http://www.fsf.org.
# ---------------------------------------------------------------------------
*#

And add it to https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HCopyrightheaderinsourcefiles

WDYT?

PS: I don’t think this would cause any perf issues.

#2

And also add it to the Maven license plugin validator.

#3

Yes definitely. Once all vm file license headers have been added.

#4

Alternative suggested by Thomas:

## ---------------------------------------------------------------------------
## See the NOTICE file distributed with this work for additional
## information regarding copyright ownership.
##
## This is free software; you can redistribute it and/or modify it
## under the terms of the GNU Lesser General Public License as
## published by the Free Software Foundation; either version 2.1 of
## the License, or (at your option) any later version.
##
## This software is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## Lesser General Public License for more details.
##
## You should have received a copy of the GNU Lesser General Public
## License along with this software; if not, write to the Free
## Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
## 02110-1301 USA, or see the FSF site: http://www.fsf.org.
## ---------------------------------------------------------------------------

I think this format looks better.

#5

+1

#6

Since Velocity is interpreted, adding new lines to parse (even if they are comments) to all templates won’t affect performances?

#7

It’s not free but I sure hope the price of comment is negligible.

#8

Also, I expect that in the future the template’s AST will be cached once after it’s read the first time for improved perfs.

#9

Did a quick test and the parsing time for the comments seems negligible. More precisely:

I executed 100000 velocity parsing with and without the license header and I got:

With:

  • time1 = 19669, time2 = 19261, time3 = 19538
  • avg = 19489 ms

Without:

  • time1 = 17623, time2 = 16538, time3 = 16255
  • avg = 16805

Difference = 2685ms

This means 0.02 ms of difference for one parsing. Negligible.

My inputs:

input 1:

new StringReader("###\n"
    + "### Annotations page in the \"view\" mode\n"
    + "###\n"
    + "###\n"
    + "#if(\"$!request.xpage\" == 'annotations')\n"
    + "  $response.sendRedirect($doc.getURL('view', 'viewer=annotations'))\n"
    + "#else\n"
    + "  #set($titleToDisplay = $services.localization.render('core.viewers.annotations.title', [\"<a href='$doc.getURL()'>$escapetool.xml($doc.getPlainTitle())</a>\"]))\n"
    + "  #template('contentheader.vm')\n"
    + "  #template(\"annotationsinline.vm\")\n"
    + "#end"));

input 2:

new StringReader("##---------------------------------------------------------------------------\n"
                    + "## See the NOTICE file distributed with this work for additional\n"
                    + "## information regarding copyright ownership.\n"
                    + "##\n"
                    + "## This is free software; you can redistribute it and/or modify it\n"
                    + "## under the terms of the GNU Lesser General Public License as\n"
                    + "## published by the Free Software Foundation; either version 2.1 of\n"
                    + "## the License, or (at your option) any later version.\n"
                    + "##\n"
                    + "## This software is distributed in the hope that it will be useful,\n"
                    + "## but WITHOUT ANY WARRANTY; without even the implied warranty of\n"
                    + "## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n"
                    + "## Lesser General Public License for more details.\n"
                    + "##\n"
                    + "## You should have received a copy of the GNU Lesser General Public\n"
                    + "## License along with this software; if not, write to the Free\n"
                    + "## Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA\n"
                    + "## 02110-1301 USA, or see the FSF site: http://www.fsf.org.\n"
                    + "## ---------------------------------------------------------------------------\n"
                    + "###\n"
                    + "### Annotations page in the \"view\" mode\n"
                    + "###\n"
                    + "###\n"
                    + "#if(\"$!request.xpage\" == 'annotations')\n"
                    + "  $response.sendRedirect($doc.getURL('view', 'viewer=annotations'))\n"
                    + "#else\n"
                    + "  #set($titleToDisplay = $services.localization.render('core.viewers.annotations.title', [\"<a href='$doc.getURL()'>$escapetool.xml($doc.getPlainTitle())</a>\"]))\n"
                    + "  #template('contentheader.vm')\n"
                    + "  #template(\"annotationsinline.vm\")\n"
                    + "#end\n"));

So, in addition the comments represent a large portion of this template which makes it worse than the reality probably.

#10

Done in https://jira.xwiki.org/browse/XCOMMONS-1841

#11

Another idea would be to use a different syntax for the license headers for VM files and remove it at build time with Maven. For example by using the Maven Resources plugin and implementing some custom resource filter (http://maven.apache.org/plugins/maven-resources-plugin/examples/custom-resource-filters.html). The requirement for license header is to have them only in sources but not in binaries.

#12

The not so esy part here is that we have different modules containing vm files and they use different maven plugins to package them: assembly plugin, war plugin, resources plugin. So it would mean inserting the execution of some custom plugin to remove the headers and copy the files in the target dir and then modify the pom.xml to make sure that the assembly plugin, war plugin & resources plugin get the vm files from the target dir.