projectdoc Toolbox

Renders document history information.

Audience: Author, Template Author
Since: 1.10.2

The Changelog Macro renders the changes of a given page as a table. The user selects the change information to show.

The macro allows to render selected information. This is especially handy for use cases where change information is exported (for instance to PDF).

Screenshot of the macro

Compare to Change-History Macro

This macro is similar to the Change-History Macro that is part of the Confluence installation.

The projectdoc version has the following features:

Control the order and content of the columns
Define column headings
Define the date format
Filter on comments
Suppress changes with no comment
Specify the page (not necessarily the page the macro is on)

Options of the macro

To organize your collaborative work on a document, you may use a Charter. The Changelog Macro may be use on the charter document to track changes on the document the team is working on. This would support the team compiling of change information for the final document.

Properties

Columns

Specify the identifier of change attributes to show. The order of the identifiers defines the order of the columns.

Valid identifiers are:

Identifier	Default Label	Description
`user`	Author	The user responsible for the change.
`date`	Date	The date when the change has been made.
`comment`	Comment	The comment given by the user to describe the change. This information may not be provided by the user.
`comment+version`	Comment	The comment as above plus a link to the previous version.

There is a default label for each identifier. If you want to render a different label, specify it after the identifier and separate it with the equal sign ('=').

Specify Labels

user=Committer, date=Modification Date, comment

In this example the labels for user and comment are changed to custom values.

Date Format

The date format defines how dates are rendered. The rules for valid formats are specified in Date Format.

The date format also controls how changes are rendered. All change comments by a given user and on the given date are rendered in the comment column of a row.

If the format references the day 20.02.2015 then every change comment by a given user on that day is rendered in the same table cell.

Comment Filter

Specify a regular expression to select the changes to render in the table.

There may be many change comments, but only a few are important enough to render them in the changelog table. Typically teams define a prefix to add before every comment. The matched text in the first pair of brackets is rendered.

If the comment filter is set to

commit: (.+)

only changes where the comment starts with "commit: " are selected. The comment column only shows the part after this prefix.

Empty Comment Handling

Teams may decide to not comment every change. These changes may not be rendered in the changelog table.

Simply check the box to drop all changes without a comment (this is the default).

Transclusions

Check this box to include changes from pages transcluded via the Transclusion Macro.

Select comment+version for a column to render changes within transcluded documents.

Experimental Feature

The limitations of this experimental feature are:

Changes are tracked on page level. The macro does not check if the page changed within the transcluded fragment. If the page from which content is transcluded changes, it is added to the list of changes.
Since only the Transclusion Macro is taken into account, changes to the page contributed by other macros are not reflected. This may confuse users.
- Dynamic content is not tracked since it is currently not synchronized: for instance Transclude Documents Macro and Display Table Macro
- Transclusions from display macros are not tracked: Display Document Property Macro and others
The change is rendered with the identifier of the change, which includes the identifier of the page's history version (not only the version ID).

We recommend to use this feature to get an overview over changes. Do not apply this feature to use cases where it is mandatory to track all changes to a document.

Page

Specify the page to render its changes. If no page is specified, the macro renders the changelog of the page this macro is part of.

Resources

Charter: Describes an information need and use this description as a basis to create and maintain a document.
Paperwork: Collaborate to create documents for your stakeholders as a team.
Domain Crunching: Collect and maintain information relevant for your team, project, or organization collaboratively.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal