Changes for page Maven XAR Plugin

Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -194,18 +194,64 @@
194	194	</entries>{{/code}}
195	195	{{/warning}}
196	196
	197	+= Format & Verify Mojo =
	198	+
	199	+{{info}}12.3RC1{{/info}}There are 4 types of pages that can be defined using regexes:
	200	+* Technical Pages: This is the default. It means pages must be hidden and not have any default language set.
	201	+* Content Pages: These are pages having content and that can have translations. These pages must not be hidden and must have a non-empty default language (so that the XWiki search return results for them when the English language is selected in language facet for example). Example:(((
	202	+{{code language="xml"}}
	203	+<plugin>
	204	+ <groupId>org.xwiki.commons</groupId>
	205	+ <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
	206	+ <configuration>
	207	+ <contentPages>
	208	+ <contentPage>.*/Space[1-9]*/WebHome\.xml</contentPage>
	209	+ </contentPages>
	210	+ </configuration>
	211	+</plugin>
	212	+{{/code}}
	213	+)))
	214	+* Translatable Pages: These are technical pages but that can have translations. It means pages must be hidden and have a non-empty default language. When not specified it defaults to ##.*/.*Translations\.xml##, which corresponds to XWiki platform's best practice for naming wiki translation pages. Override example:(((
	215	+{{code language="xml"}}
	216	+<plugin>
	217	+ <groupId>org.xwiki.commons</groupId>
	218	+ <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
	219	+ <configuration>
	220	+ <translatablePages>
	221	+ <translatablePage>.*/Translations\.xml</translatablePage>
	222	+ </translatablePages>
	223	+ </configuration>
	224	+</plugin>
	225	+{{/code}}
	226	+)))
	227	+* Visible Technical Pages: These are technical pages but that must be visible but that shouldn't return results in Search. For example, home pages of applications. They must not be hidden but they must have their default language set to empty. Example:(((
	228	+{{code language="xml"}}
	229	+<plugin>
	230	+ <groupId>org.xwiki.commons</groupId>
	231	+ <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
	232	+ <configuration>
	233	+ <visibleTechnicalPages>
	234	+ <visibleTechnicalPage>.*/Space/WebHome\.xml</visibleTechnicalPages>
	235	+ </visibleTechnicalPages>
	236	+ </configuration>
	237	+</plugin>
	238	+{{/code}}
	239	+)))
	240	+
197	197	= Format Mojo =
198	198
199		-To use it:
	243	+[[Older documentation for versions < 12.3RC1>>||path:$doc.getURL('viewrev', queryString="rev=30.1#HFormatMojo")]].
200	200
	245	+To use the mojo:
	246	+
201	201	* ##mvn xar:format## will perform some cleaning of your XML files, namely:
202	202	** Indent lines (using 2 space characters)
203	203	** Set ##author##, ##contentAuthor##, ##creator## and attachment ##author##s to be ##xwiki:XWiki.Admin##
204	204	** Set ##version## to be 1.1
205	205	** Set ##minorEdit## to be false
206		-** Remove any content of the ##defaultLanguage## element unless the document has translations. Indeed, if a document has translation we assume it means the document is not a technical document and thus we set the default language to be English. This allows the XWiki SOLR Search to return results when the English language is selected in language facet.
	252	+** Remove any content of the ##defaultLanguage## element unless the document has translations, or it's marked as a ##translatablePage## or it's marked as a ##contentPage## (see above).
207	207	** Remove any content of the ##comment## element
208		-** {{info}}New in 5.4RC1{{/info}} Add any missing license header by using the license defined in ##xwiki-commons-tool-verification-resources## JAR. License headers will be checked if the ##formatLicense## configuration parameter is set to true:(((
	254	+** Add any missing license header by using the license defined in ##xwiki-commons-tool-verification-resources## JAR. License headers will be checked if the ##formatLicense## configuration parameter is set to true:(((
209	209	{{code language="xml"}}
210	210	<plugin>
211	211	<groupId>org.xwiki.commons</groupId>
...	...	@@ -218,58 +218,29 @@
218	218	</plugin>
219	219	{{/code}}
220	220	)))
221		-** {{info}}New in 7.3M1{{/info}} Technical pages are marked hidden. To mark a page as technical use the ##technicalPages## configuration element as in:(((
222		-{{code language="xml"}}
223		-<plugin>
224		- <groupId>org.xwiki.commons</groupId>
225		- <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
226		- <version>${commons.version}</version>
227		- <configuration>
228		- <technicalPages>
229		- <technicalPage>.*/.*Translations\.xml</technicalPage>
230		- </technicalPages>
231		- </configuration>
232		-</plugin>
233		-{{/code}}
234		-)))
	267	+** Technical pages are marked hidden. Same for translatable pages.
235	235	** {{info}}New in 10.8RC1{{/info}} Remove any ##date##, ##creationDate##, ##contentUpdateDate## or attachment ##date## fields, regardless if they have empty values or not. This is done because it's causing confusion for users to install pages that are created in 2005/2009/etc. so we should avoid committing dates on git that users might end up installing.
236	236	*** Can be disabled for individual pages with either ##-Dxar.dates.skip.documentList=Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc.## (system property) or ##<skipDatesDocumentList>Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc.</skipDatesDocumentList>## (plugin configuration parameter).
237	237	*** Can be disabled for all pages in the xar with either ##-Dxar.dates.skip=true## (system property) or ##<skipDates>true</skipDates>## (plugin configuration parameter).
238		-** {{warning}}New in 11.10.3 and 12.0RC1{{/warning}}The ##technicalPage## and ##contentPage## entries in the plugin configuration now accept a regex that will be tested on the full path of the file. Before the regex was tested only on the file name. This allows supporting spaces.
239	239
240	240	= Verify Mojo =
241	241
	274	+[[Older documentation for versions < 12.3RC1>>||path:$doc.getURL('viewrev', queryString="rev=30.1#HVerifyMojo")]].
	275	+
242	242	This is used to fail the build if the XML pages don't conform to the following rules:
243	243
244	244	* Verify that the encoding is UTF-8
245	245	* Verify that ##author##, ##contentAuthor##, ##creator## and attachment ##author##s are set to ##xwiki:XWiki.Admin##
246		-* Verify that the ##parent## field is not empty (except for ##Main.WebHome##)
	280	+* Verify that the ##parent## field is not empty (except for ##Main.WebHome##). This check became optional (and turned off by default) in XWiki 11.10.3 & 12.0RC1.
	281	+** To turn if on, set ##<emptyParentSkip>false</emptyParentSkip>## in the POM or pass ##-Dxar.verify.translationVisibility.skip=false## on the Maven command line
247	247	* Verify that ##version## is set to 1.1
248	248	* Verify that ##comment## is empty
249	249	* Verify that ##minorEdit## is set to false
250		-* Verify that the ##defaultLanguage## is empty for technical documents or the configured language in the mojo (by default ##en##, it's configurable in the ##<configuration>##, for example ##<defaultLanguage>fr</defaultLanguage>##) for documents having translations (which we assume are not technical documents). If a page has translations then we consider it as a content page, otherwise we consider it a technical document. Note that since version 7.1 it's possible to provide a white list of content and technical pages (when both are specified and matching, content pages take precedence since 7.3; before 7.3 technical pages used to take precedence). For example:(((
251		-{{code language="xml"}}
252		-<plugin>
253		- <groupId>org.xwiki.commons</groupId>
254		- <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
255		-...
256		- <configuration>
257		-...
258		- <!-- Consider all pages named *Translations as content pages by default -->
259		- <contentPages>
260		- <contentPage>.*/.*Translations\.xml</contentPage>
261		- </contentPages>
262		- <!-- The EditTranslations page is not a Translation page and thus not a content page! -->
263		- <technicalPages>
264		- <technicalPage>.*/EditTranslations\.xml</technicalPage>
265		- </technicalPages>
266		- </configuration>
267		-</plugin>
268		-{{/code}}
269		-)))
	285	+* Verify that the ##defaultLanguage## is empty for technical documents and ##visibleTechnicalPage##s (see above).
	286	+* Verify that the ##defaultLanguage## is not empty for ##contentPage##s and ##translatablePage##s (see above) and it matches the configured language in the mojo (by default ##en##, it's configurable in the ##<configuration>##, for example ##<defaultLanguage>fr</defaultLanguage>##).
270	270	* (optional) Verify that the XML files contain license headers (if the ##formatLicense## configuration property is set to ##true##).
271		-* {{info}}New in 7.3M1{{/info}} Verify that Technical pages are set as hidden. See the Format mojo above.
272		-* {{info}}New in 7.3{{/info}} Verify that defined pages have a specific matching title. For example:(((
	288	+* Verify that technical pages, and ##translatablePage##s are set as hidden, and that ##contentPage##s and ##translatablePage##s are set as npot hidden.
	289	+* Verify that defined pages have a specific matching title. For example:(((
273	273	{{code language="xml"}}
274	274	<plugin>
275	275	<groupId>org.xwiki.commons</groupId>
...	...	@@ -288,13 +288,12 @@
288	288	</plugin>
289	289	{{/code}}
290	290	)))
291		-* {{info}}New in 8.1M1{{/info}} Verify that Translations pages (i.e. documents with a ##XWiki.TranslationDocumentClass## xobject) are using the ##plain/1.0## syntax.
	308	+* Verify that Translations pages (i.e. documents with a ##XWiki.TranslationDocumentClass## xobject) are using the ##plain/1.0## syntax.
292	292	* {{info}}New in 10.1RC1{{/info}} Verify that Translations pages don't have a GLOBAL or USER visibility (USER makes no sense and GLOBAL would require Programming Rights, which is an issue in farm-based use cases). This check can be ignore by using the ##translationVisibilitySkip## configuration option (or ##xar.verify.translationVisibility.skip## on the command line).
293	293	* {{info}}New in 10.6RC1{{/info}} Verify that attachments have a mimetype set. If the mimetype is missing then the attachment won't be filterable in the attachment view in Page Index.
294	294	* {{info}}New in 10.8RC1{{/info}} Verify that any ##date##, ##creationDate##, ##contentUpdateDate## or attachment ##date## fields are not specified, thus risking to import pages with stale dates.
295	295	** Can be disabled for individual pages with either ##-Dxar.dates.skip.documentList=Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc.## (system property) or ##<skipDatesDocumentList>Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc.</skipDatesDocumentList>## (plugin configuration parameter).
296	296	** Can be disabled for all pages in the xar with either ##-Dxar.dates.skip=true## (system property) or ##<skipDates>true</skipDates>## (plugin configuration parameter).
297		-* {{warning}}New in 11.10.3 and 12.0RC1{{/warning}}The ##technicalPage## and ##contentPage## entries in the plugin configuration now accept a regex that will be tested on the full path of the file. Before the regex was tested only on the file name. This allows supporting spaces.
298	298
299	299	Example usage:
300	300