Difference between revisions of "Maven distro directory layout"

From Gcube Wiki
Jump to: navigation, search
(README)
(README)
Line 65: Line 65:
 
--------------------------------------------------
 
--------------------------------------------------
 
   
 
   
Bugs and support requests can be reported in the gcube issue tracking tool:
+
Bugs and support requests can be reported in the gCube issue tracking tool:
 
     ${gcube.issueTracking}
 
     ${gcube.issueTracking}
 
   
 
   
Line 84: Line 84:
 
* the component pom.xml. It is possible to access custom-defined properties in the section <code><properties></code> of the pom as well as default properties defined by Maven (e.g. <code>${version}</code>, <code>${name}</code>);
 
* the component pom.xml. It is possible to access custom-defined properties in the section <code><properties></code> of the pom as well as default properties defined by Maven (e.g. <code>${version}</code>, <code>${name}</code>);
 
* the gCube <code>maven-parent</code> (available [http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-externals/org/gcube/tools/maven-parent/ here]);
 
* the gCube <code>maven-parent</code> (available [http://maven.research-infrastructures.eu/nexus/content/repositories/gcube-externals/org/gcube/tools/maven-parent/ here]);
The properties are replaced during the build by the [https://maven.apache.org/shared/maven-filtering/ filtering mechanism] used by the plugins that create the distribution packages (i.e. the [http://maven.apache.org/plugins/maven-assembly-plugin/ assembly pluygin]).
+
The properties are replaced during the build by the [https://maven.apache.org/shared/maven-filtering/ filtering mechanism] used by the plugins that create the distribution packages (i.e. the [http://maven.apache.org/plugins/maven-assembly-plugin/ assembly plugin]).
  
=== Common properties ===
+
These are the properties used in the README template provided above:
Following properties are
+
{| class="wikitable"
 +
! property
 +
! definition
 +
! description
 +
|-
 +
| ${name}
 +
| pom.xml
 +
| The value of <code><name></code> tag in the pom
 +
|-
 +
| ${description}
 +
| pom.xml
 +
| The value of <code><description></code> tag in the pom
 +
|-
 +
| ${gcube.description}
 +
| maven-parent
 +
| A brief description of gCube framework
 +
|-
 +
| ${gcube.funding}
 +
| maven-parent
 +
| The declaration of EU projects that funded the gCube development
 +
|-
 +
| ${version}
 +
| pom.xml
 +
| The value of <code><version></code> tag in the pom
 +
|-
 +
| ${buildDate}
 +
| maven-parent
 +
| The date of the component build. It is in the YYYY-MM-dd format (format defined in maven-parent)
 +
|-
 +
| ${scm.url}
 +
| pom.xml
 +
| The location of component source code in SVN. It must be defined in the pom in <code><scm><url>[location]</url></scm></code>
 +
|-
 +
| ${gcube.website}
 +
| maven-parent
 +
| The website of gCube system: http://gcube-system.org/
 +
|-
 +
| ${gcube.wikiRoot}
 +
| maven-parent
 +
| The home page of the gCube wiki: https://gcube.wiki.gcube-system.org/gcube/index.php/
 +
|-
 +
| ${gcube.issueTracking}
 +
| maven-parent
 +
| The home page of the gCube Issue Tracker: https://support.d4science.org/projects/gcube/
 +
|}
  
 
== LICENSE ==
 
== LICENSE ==

Revision as of 16:55, 3 March 2016

The guidelines provided in this page have been decided and being adopted starting from March 2015

distro

README

Each gCube component must include a README file that must be included in distribution packages of the component. The file briefly describe the component and the gCube system and provide references to the source code, binaries, documentation as well as to the INSTALL and LICENSE file.


In order to have as much as possible uniform README files across components and to reduce the effort to maintain the file updated, a standardized template is provided. The template makes use of placeholders (delimited by ${...}) that are replaced at build-time with the value of Maven properties. This approach allows to keep the same README in the source code while distributing files containing always updated information.


By convention, the README file should be located under the distro/ folder (together with the other metadata files: LICENSE, MAINTAINERS, INSTALL, ...). It should follow this template (only minor changes to fits the component needs are allowed):


The gCube System - ${name}
--------------------------------------------------
 
${description}
 
 
${gcube.description}
 
${gcube.funding}
 
 
Version
--------------------------------------------------
 
${version} (${buildDate})
 
 
Authors
--------------------------------------------------
 
* John Doe (john-AT-acme.org), Acme Inc., New York.* [other maintainers] 
 
Download information
--------------------------------------------------
 
Source code is available from SVN: 
    ${scm.url}
 
Binaries can be downloaded from the gCube website: 
   ${gcube.website}
 
 
Documentation 
--------------------------------------------------
 
Documentation is available on-line in the gCube Documentation Wiki:
    Developer Guide - ${gcube.wikiRoot}/[page name here]    User Guide - ${gcube.wikiRoot}/[page name here]    Admin Guide - ${gcube.wikiRoot}/[page name here] 
Installation
--------------------------------------------------
 
Please see the file named "INSTALL" in this directory.
 
 
Support 
--------------------------------------------------
 
Bugs and support requests can be reported in the gCube issue tracking tool:
    ${gcube.issueTracking}
 
 
Licensing
--------------------------------------------------
 
This software is licensed under the terms you may find in the file named "LICENSE" in this directory.


The highlighted lines in the template should be replaced with appropriate data for the component before commit it in SVN. It is very static information and use dynamic property values for that does not have any advantage. In any case developers are free to define properties in their pom.xml and use them in the README file.


All the placeholders delimited by ${...} must correspond to Maven properties. There are two source of properties:

  • the component pom.xml. It is possible to access custom-defined properties in the section <properties> of the pom as well as default properties defined by Maven (e.g. ${version}, ${name});
  • the gCube maven-parent (available here);

The properties are replaced during the build by the filtering mechanism used by the plugins that create the distribution packages (i.e. the assembly plugin).

These are the properties used in the README template provided above:

property definition description
${name} pom.xml The value of <name> tag in the pom
${description} pom.xml The value of <description> tag in the pom
${gcube.description} maven-parent A brief description of gCube framework
${gcube.funding} maven-parent The declaration of EU projects that funded the gCube development
${version} pom.xml The value of <version> tag in the pom
${buildDate} maven-parent The date of the component build. It is in the YYYY-MM-dd format (format defined in maven-parent)
${scm.url} pom.xml The location of component source code in SVN. It must be defined in the pom in <scm><url>[location]</url></scm>
${gcube.website} maven-parent The website of gCube system: http://gcube-system.org/
${gcube.wikiRoot} maven-parent The home page of the gCube wiki: https://gcube.wiki.gcube-system.org/gcube/index.php/
${gcube.issueTracking} maven-parent The home page of the gCube Issue Tracker: https://support.d4science.org/projects/gcube/

LICENSE

${gcube.license}

https://joinup.ec.europa.eu/sites/default/files/ckeditor_files/files/eupl%20v%20%201%201%20-%20EN.txt.txt