All SCM must be able to write and parse a change log in order to be able to show it per build. The change log file is most of the times a simple XML file. The SCM must implement the method createChangeLogParser that delegates the parsing of the change log file to the SCM which returns a ChangeLogSet derivate. It is the responsibility of the checkout method to write the XML file, which then is parsed after the checkout method returns. To be able to show the changes in a build, two jelly files are used.
The ChangeLogSet object represents a SCM change list. It contains zero or more change log entries that extends ChangeLogSet.Entry.
A ChangeLogSet.Entry derivate should contain data about a change in a SCM. What information that should be stored depends on the SCM. There are three abstract methods that must be implemented.
Should return a collection of file paths that was affected in the change log entry.
Should return the author of the change. Hudson automatically creates a User object for all users that is stored in a change log entry.
Returns the message that was attached to the change log entry. Also known as commit message.
If you would like to display an icon next to the change set or files in the change set that shows what type of action it was, you should implement a method that returns an EditType. The method is then used by the index.jelly to determine which icon to display.
The change log is saved per build, and most of the times it is an XML file. The change log must be stored by the SCM in the checkout() method, the name of the file is supplied in the checkout() method.
The Team Foundation Server plugin is using the below XML format.
Most of the times a very simple text writer is adequate for creating the XML file.
The change log is then parsed by Hudson during a build (after the SCM is done) so the changes in the build can be displayed in the Status and Changes page. The SCM method createChangeLogParser must return an object that can parse the XML file and return a ChangeLogSet derivate. Using digester it is very simple to parse an XML file and create objects from it, the only downside is that the classes that must have a default constructor.
The parsed change log items (change sets) should then be put into a ChangeLogSet derivate object that is returned by ChangeLogParser.parse(). Note that the object's class that is used to parse the change log file is stored in the build.xml, so it is not advisable to change name of the parser class later.
The jelly files are used to display the ChangeLogSet for each build. The files should be stored src/main/resources/hudson/plugins/scm/[pluginname]/ChangeLogSetDerivate folder.
The digest.jelly file is used to display the change log on the status page. The listing should be brief and most of the time only display the change message.
The above jelly code, will loop through ChangeLogSet.getLogs() and display the annotated message and a link to the Changes page.
The index.jelly file is used to display a detailed change log on the Changes page. The listing should include all data that is available in each change log entry.
The above jelly code will first display a listing of all change sets, with each change message. For each change set it will display the version number, a link to the author and annotated message and a list of changed items/files.
The change log entry must have a reference to the change log set that it is part of. The method ChangeLogEntry.setParent() is used to set the parent log set.
The change log entries should have the @ExportedBean(defaultVisibility=999) so it is available through the Hudson XML api. Each get method that should be available in the XML api is marked with @Exported, as most of the get methods in the class.
The hudson.Util.XS_DATETIME_FORMATTER can help when writing and reading date objects to and from XML.
Skip to end of metadata Go to start of metadata