Difference between revisions of "Maven distro directory layout"
(→README) |
(→README) |
||
Line 20: | Line 20: | ||
By convention, the README file should be located under the <code>distro/</code> 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): | By convention, the README file should be located under the <code>distro/</code> 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): | ||
− | <source lang="text" highlight="34,35,36"> | + | <source lang="text" highlight="34,35,36,49,50"> |
The gCube System - ${name} | The gCube System - ${name} | ||
-------------------------------------------------- | -------------------------------------------------- | ||
Line 69: | Line 69: | ||
-------------------------------------------------- | -------------------------------------------------- | ||
− | Please see the file named "MAINTAINERS" in this directory. | + | * John Doe (john.doe@acme.org), ACME Inc. |
+ | * Second Author(email@example.org), Organization, Country | ||
+ | |||
+ | Please see the file named "MAINTAINERS" in this directory for the current maintainers of this software. | ||
Line 87: | Line 90: | ||
− | The <span style="background-color: #ffc">highlighted lines</span> 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 <code>pom.xml</code> and use them in the README | + | The <span style="background-color: #ffc">highlighted lines</span> 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 (and, in case of authors, technically difficult). In any case developers are free to define properties in their <code>pom.xml</code> and use them in the README. |
Revision as of 11:19, 4 March 2016
The guidelines provided in this page have been adopted starting from March 2015
distro directory
This directory contains a set of files and templates of files that will be included in the distribution packages of the component. This process is done through the Maven assembly plugin (controlled by the descriptor.xml
file) located in this folder).
The following sections describes the common files that ALL components must provide. This directory can also contains other component-specific files required to be distributed in the component packages.
Important note: The layout, the files and the filtering mechanism presented in this section work only for Maven components. They will not work with the Ant components. Also Ant components must provide such files, but, since Ant does not provide any support for filtering of files, developers must take care of keep the files updated manually.
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}) Please see the file named "changelog.xml" in this directory for the release notes. 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] Support -------------------------------------------------- Bugs and support requests can be reported in the gCube issue tracking tool: ${gcube.issueTracking} Authors and Maintainers -------------------------------------------------- * John Doe (john.doe@acme.org), ACME Inc.* Second Author(email@example.org), Organization, Country Please see the file named "MAINTAINERS" in this directory for the current maintainers of this software. Installation -------------------------------------------------- Please see the file named "INSTALL" in this directory. 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 (and, in case of authors, technically difficult). In any case developers are free to define properties in their pom.xml
and use them in the README.
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
This file (referenced by the README file) contains the text of the license under which the software is distributed. In order to avoid massive update of this file in all components if in the future, the gCube license will change, the entire text of this file is provided by a Maven property defined in the maven-parent: ${gcube.license}
${gcube.license}
Currently the license under which gCube is distributed is the EUPL v1.1 and the ${gcube.license}
is replaced with this text.
MAINTAINERS
The MAINTAINERS file (referenced by the README) should provide name and contacts of the authors and maintainers (if different) of the component.
Authors ------- * Manuele Simi (manuele.simi@isti.cnr.it), CNR Pisa, Istituto di Scienza e Tecnologie dell'Informazione "A. Faedo" * Andrea Manzi (andrea.manzi@cern.ch), CERN, Geneva Maintainers ------- * Ciro Formisano (ciro.formisano@eng.it) Engineering Ingegneria Informatica S.p.A., Rome (IT)
INSTALL
This file should briefly provide instructions to install the component.
changelog.xml
This file (referenced by the README) contains the list of all changes, fixes and new features for each release of the component.An example of changelog.xml file is:
<ReleaseNotes> <Changeset component="org.gcube.messaging.consumer.1-2-0" date="2010-07-16"> <Change>Extended the Monitoring Generic Resource with the possibility to specify site managers for each site domain</Change> <Change>Notification are now filtered over domain</Change> <Change>Added daily notification summary</Change> </Changeset> <Changeset component="org.gcube.messaging.consumer-library.1-1-2" date="2010-07-16"> <Change>Added queries for NodeAccounting portlet</Change> </Changeset> </ReleaseNotes>
This file contribute to the generation of the full gCube release changelog. In order to correctly generate the final changelog, the value of component tag must match exactly the name of the ETICS Configuration, therefore it is wrong to put here ${name}
(unless the name of the component matches the name of the ETIC configuration.
Further information can be found in the Changelog Generation procedure page.