This page documented documents all changes which affect public usage. For a complete list see JIRA project releases.
Table of Contents | ||
---|---|---|
|
General
- Upgrade to Java 8
- Upgrade to Maven 3.2.5 prerequisite
- Move to SLF4J everywhere
- Replace Plexus Container with Sisu Shim
- Use JSR 330 annotations instead of Plexus one
- Partially breaking behavior to overcome 10+ years of technical debt (previous big step was the full extraction of Doxia 1.1 from Maven core in 2010, followed by a non-breaking maintenance phase for 10 years...)
Stack
The entire stack consists of multiple components which make up the entire system to produce and render documents for Maven sites and report plugins: the wider overview is available in Maven Site Plugin documentation.
Doxia 2.0.0
- Remove Doxia Logging API (replaced by SLF4J)
- Remove deprecated macros (SWF, SSI)
- Remove deprecated modules (:
- old formats: Confluence, DocBook, TWiki
- page-oriented output formats: FOP, iText, LaTeX, RTF
- Remove deprecated code
- Replace XHTML module with XHTML5 as default
- Section titles (see Doxia API sectionTitle(int) API) are now converted to HTML
<h1>
to <h5> to<h6>
(Doxia API sectionTitle1() to Doxia API sectionTitle6()) for XHTML5 instead of from<h2>
- Upgrade to Flexmark 0.62.2
- Remove all non-HTML5 elements and attributes
- Use id attribute for XHTML5 throughout instead of name for anchors
- Change notion for verbatim content
Correct semantics of
SinkEventAttributes#BOXED
with#SOURCE
- Create consistent Doxia IDs throughout based on XML id definition
- Optionally create anchors for indexable entires (used in TOC macro)
- Sink implementations must only implement overloaded Doxia 1.1/2.0 methods (taking an additional argument
SinkEventAttributes
). The overloaded Doxia 1.0 variants only delegate to the Doxia 1.1/2.0 equivalent as final methods inAbstractSink
and therefore must no longer be implemented anywhere else (
)Jira server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b key DOXIA-709
Further details in Jira release notes: https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12354039&styleName=Html&projectId=12317230
Doxia Sitetools 2.0.0
- Upgrade to Doxia 2.0.0
- Remove DocRenderer = document-oriented rendering, leaving only SiteRenderer in place = site-oriented rendering
- Remove deprecated code
- Fail if deprecated
${reports}
,${parentProject}
or${modules}
is found - Upgrade to Velocity 2.3 and Velocity Tools 3.1
- Require a skin if a site descriptor (
site.xml
) has been provided - Don't inject bannerLeft is none is set
- Locale must not be
null
- Deprecate and remove Google-related site descriptor properties
- Don't create anchors behind the user's back (avoid mess and duplication)
- Remove internal (pseudo) skin and use Maven Fluido Skin by default
- Overhaul locale support (make
Locale#ROOT
instead ofLocale#ENGLISH
default and use full locale) - Don't link modules if module isn't part of the reactor or site hasn't been generated
- Remove support for Maven 1.x style site directory layout
- Add time zone field to site descriptor for reproducible site; defaults to
Etc/UTC
- Replace skin and site descriptor resolution with Maven Resolver API
- Rename
RenderingContext
toDocumentRendeneringContext
- Rename
Renderer
toSiteRenderer
- Rename Doxia Decoration Model to Maven Site Model along with package and root class
- Transparently handle 0-byte pseudo marker site descriptors
- Harmonize path output for rendered documents
- Introduction of a new, more streamlined and clean up site model (old one is converted on the fly)
DocumentRenderer#getOutputName()
has been deprecated in favor of#getOutputPath()
DocumentRenderingContext#getInputName()
/#getOutputName()
have been deprecated in favor of#getInputPath()/#getOutputPath()
- Velocity context properties
$alignedFileName
,
$currentFileName
,
$decoration
have been deprecated in favor of$alignedFilePath
,
$currentFilePath,
$site
Maven Reporting API 4.0.0
- Upgrade to Doxia 2.0.0
- Locale must not be null (use
Locale#ROOT
instead) MavenReport#canGenerateReport()
can now throw an exceptionMavenReportRenderer#render()
can now throw an exceptionMavenReport#getOutputName()
has been deprecated in favor of#getOutputPath()
- Refined definition of runtime behavior
Maven Reporting Impl 4.0.0
- Upgrade to Maven Reporting API 4.0.0
- Upgrade to Doxia 2.0.0
- Upgrade to Doxia Sitetools 2.0.0
- Render with a skin when report plugin is run in standalone mode (defaults to Maven Fluido Skin)
- Notify skin via Velocity context property whether running in standalone or site mode
- Properly use
SinkEventAttributes#SOURCE
by providing#verbatimText()
and#verbatimSource
- Propagate
${project.build.outputTimestamp}
and$publishDate
- Remove duplicate autogenerated anchors
- Use site decoration like Maven Site Plugin when run in standalone mode, but without navigation. Focus on report.
- Support markdown output instead of HTML site
- Refined definition of runtime behavior
- Consistently log when report execution is skipped
- The output directory properly differs when a plugin is run in standalone mode compared to site mode
Maven Reporting Exec 2.0.0
- Upgrade to Maven Reporting API 4.0.0
- Upgrade to Doxia 2.0.0
- Remove usage of deprecated local repository
Maven Site Plugin 4.0.0
- Upgrade to Maven Reporting API 4.0.0
- Upgrade to Doxia 2.0.0
- Upgrade to Doxia Sitetools 2.0.0
- Upgrade to Maven Reporting Exec 2.0.0
- Execute reports for all configured locales
- Overhaul locale support (make
Locale#ROOT
instead ofLocale#ENGLISH
default and use full locale) - Propagate
${project.build.outputTimestamp}
and$publishDate
- Make external reports run/served with
site:run
- Reserved XML chars are properly escaped
- Many locale awareness fixes
- Mark several mojos as thread-safe
- Consisntly log information what type and how many documents are rendered (include site plugin internal ones)
- Turn sitemap into a report
- Improve output of source/generator for
site:run
- Consistently log when report execution is skipped
Maven Fluido Skin 2.0.0
- Upgrade to Doxia Sitetools 2.0.0
- Reserved XML chars are properly escaped
- Fix CSS-related issues
- Support standalone mode
- Improve Doxia integration
- Rewrite skin template for new site model
Progress
Necessary changes performed at our (reporting) plugins
Format: {jira-project}
: {last-doxia-1.x-compat}
; {branch-for-doxia-2.0.0}
: {version-next}
- MPIR: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: 4.0.0-M1-SNAPSHOT
- MPLUGIN: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: x-SNAPSHOT
- JXR: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: 4.0.0-M1-SNAPSHOT
- MPMD: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: 4.0.0-M1-SNAPSHOT
- MJAVADOC: api-3.1.1 [X]; doxia-2.0.0: 4.0.0-M1-SNAPSHOT
- MCHECKSTYLE: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: 4.0.0-M1-SNAPSHOT
- MCHANGES: Won't do, plugin has too many dependencies
- MPH: api-3.1.1 [X]; doxia-2.0.0: x-SNAPSHOT
- SUREFIRE: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: x-SNAPSHOT
- MPDF: api-3.1.1 [X]; no upgrade, page-oriented support has been removed
- MDEP: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: x-SNAPSHOT
- MINVOKER: api-3.1.1/impl-3.2.0 [X]; doxia-2.0.0: x-SNAPSHOT
- MSKINS Fluido: 1.11.x; master: 2.0.0-M8
Migration Notes
Reporting Plugin Maintainers
- Sink tables must start with
Sink#table()
+Sink#tableRows()
and end withSink#tableRows_()
+Sink#table_()
- Runs UTs and ITs and compare HTML output with Doxia 1.x stack. If anything breaks for you, report with us.
- Anchors must be placed before the target element
- Make sure to take care of the signature changes in the Reporting Plugin API
- When linking to output of other plugins you must calculate the default path to it dynamically
Skin Writers
- Table border attribute is not used anymore, it has been replaced with the CSS class
bodyTableBorder
- Maven Site Model is now availabe as
$site
Velocity context property
Maven Site Plugin (Reporting Plugins) Users
- When using multiple locales, make sure that you supply
default
as well otherwise no root site will be generated - You must supply a skin if you are using a site descriptor (
site.xml
) - Use Maven Fluido Skin for custom Google-related properties
- Local repository must be purged or at least stale site descriptors deleted (
find ~/.m2/repository -name \*site\*.xml -size 0 -delete
) to properly resolve remote site descriptors again (site.xml
)
Open Issues/TODOs
- Update all documentation in
src/site/
Internal
Component Release Order
maven-doxia
maven-reporting-api
maven-doxia-sitetools
maven-reporting-impl
maven-reporting-exec
maven-site-plugin
- maven-fluido-skin