element ci:modification = { element ci:message { text }, element ci:scmrevision { text }?, element atom:author+, element atom:link?, element ci:file { element ci:path { text }, element atom:link?, }+,
Note: This is still a work in progress. Nothing in this specification is correct. Not one single thing. :-)
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Can be used by Atom clients that do not understand CI specific information
Can contain "humanly" meaningful content as well as content that can be interpreted by computer systems
Not bound to specific technical platform
Show ongoing builds as well as past builds
Support both push and pull, i.e. the regardless whether the CI system send updates directly to the client or the client polls the CI system the same format can be used, this is to optimize for a large number of clients
Send information about SCM revision numbers so CI clients can associate a build with a revision
Send information about authors so that CI clients can associate a build with a user (scm login or email)
Support for pairing (multiple authors for one revision)
Open for extending with additional "vendor-specific" information, for example: test coverage, number of tests, etc.
TODO
TODO
TODO
This is equivalent to "project" in CC and "build plan" in Bamboo
This specification distinguishes between the status of a build (running or not) and it's result (failed or not). Statuses are scheduled, running, completed, not-runnable. The last status is for builds that are scheduled but can for some reason not be run, for example a CI system may not have the resources that the build requires (TBD: include this?)
failed, succeeded (build result can be sent on a running build if the CI system is capable of detecting failures before completion).
The XML namespace for the Atom extensions is http://cifeed.sf.net/schemas/0.1
CI Feeds has to comply with the Atom Syndication Format RFC 4287
Each build needs a globally unique id according to the Atom specification. This is either a GUID or a CI system unique build id combined with a unique identifier for the instance of the CI system. The URL to the build is often a good id.
The link of each entry should point to the CI systems report for that particular build.
TBD: Should we include ongoing builds or not?
The rest of this text assumes ongoing builds are included, but a CI system can choose to not include them.
We need published and updated so feed readers don't get confused: - atom\:published is the start time of the build, - atom\:updates is the time of the last activity for an ongoing build or the end time of the build for a historical build.
Semantically atom:published and atom:updated are equivalent to start/end time.
TBD: Do we also include more syntactically correct tags like ci:started / ci:finished?
We also need to include "atom:updated" for the entire feed, this is the time of the latest updated entry. This is an optimization for clients to discard the body if they have already processed entries up to this time.
The atom:term attribute of atom:category is used to specify the type of build, this is equivalent to for example project in CC or build plan in Bamboo. A single CI atom feed can contain multiple categories, how this is configured is outside the scope of this specification.
atom:title must always be included and should be a humanly readable indication of the name of the build and it's status. This is normally the same as the "Subject" of email notifications sent by the CI system.
The CI system can also include atom:summary and atom:content which should also be humanly readable. Summary is normally shorter than content and content usually includes all the information transmitted in summary.
element ci:modification = { element ci:message { text }, element ci:scmrevision { text }?, element atom:author+, element atom:link?, element ci:file { element ci:path { text }, element atom:link?, }+,
An entry can contain a number of modifications which must contain at least one file. For SCM systems and CI systems that support atomic commits one modification can contain more than one file. For CI systems that support pairing multiple authors can be specified for one modification (otherwise multiple modifications for one entry is used).
It is recommended that a CI system provide multiple versions of a particular feed. For example including all modification and test information can for some projects be very large.
Here's a few examples of feed variants that a CI system can provide:
Does not include test and modification information.
Does not include ongoing builds.
Does only include ongoing builds and potentially the previous build. Many CI clients act based on the ongoing build and the previous build.
A CI system can provide variants that include multiple or all projects in the same feed.
This specification does not require any specific transport mechanisms, but we foresee that two forms of transport will be used.
It is RECOMMENDED that CI systems at least support the traditional method of retrieving Atom feeds, a normal HTTP GET. In this scenario the client will poll the CI system at a for the client determined interval, the CI system will respond with either a for the CI system determined number of entries or if the client is identified the entries since the last poll.
A CI system MAY support pushing a CI feed update directly to the client using an HTTP POST. In this scenario only the entries since the last push need to be transmitted. A pushed feed will be more responsive as the build result can be published immediately after the end of the build and can alleviate some of the scalability issues associated with a pulling architecture.
TODO
This isn't actually completely valid Relax NG but this is just informative for now.
namespace atom = "http://www.w3.org/2005/Atom" namespace ci = "http://studios.thoughtworks.com/atom/0.1/ci" /* "extend" isn't valid Relax NG */ extend element atom:entry { element ci:status?, element ci:result?, element ci:modification?, } extend element atom:author { element ci:scmlogin? } element ci:status = { 'scheduled' | 'running' | 'completed' | 'not-runnable' } element ci:result = { 'failed' | 'succeeded' } element ci:scmlogin = { text } element ci:modification = { element ci:message { text }, element ci:scmrevision { text }?, element atom:author+, element atom:link?, element ci:file { element ci:path { text }, element atom:link?, }+, }
<?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:ci="http://studios.thoughtworks.com/atom/0.1/ci"> <title>Example Feed</title> <subtitle>A subtitle.</subtitle> <link href="http://192.168.1.201:8080/dashboard"/> <updated>2003-12-13T18:30:02Z</updated> <id>urn:uuid:60a76c80-d399-11d9-b91C-0003939e0af6</id> <entry> <title>Jruby Windows Mysql IE6 Build: build.46 Build Fixed</title> <link href="http://192.168.1.201:8080/dashboard?log=log20070730185952Lbuild.46"/> <!-- use URL instead? cc does not yet support this --> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <!-- the start time of the build --> <published>2003-12-13T18:30:02Z</published> <!-- this is the time of the last update for an ongoing build, or the time of the end of the build --> <updated>2003-12-13T18:30:02Z</updated> <icon>http://192.168.1.201:8080/dashboard/images/success.png</icon> <ci:status>completed</ci:status> <ci:result>succeeded</ci:result> <summary>Some text.</summary> <category term="Jruby Windows Mysql IE6"/> <!-- an entry has to have at least one author in Atom, so this is the set of all authors from the modifications below --> <author> <name>Jon Tirsen</name> <ci:scmlogin>jtirsen</ci:scmlogin> </author> <ci:modification> <author> <name>Jon Tirsen</name> <ci:scmlogin>jtirsen</ci:scmlogin> </author> <!-- this is the Subversion revision number in case of Subversion --> <ci:scmrevision>3618</ci:scmrevision> <!-- direct link to diff or something like that, if supported --> <link href="http://192.168.1.201:8080/dashboard?log=log20070730185952Lbuild.46"/> </ci:modification> </entry> </feed>
Other options: Completely custom XML, RSS 1.0, RSS 2.0.
RSS 2.0 is not standardized by a standards body.
RSS 2.0's copyright does not allow it to be modified thus making it legally impossible to extend it with CI-specific information.
Build information share most properties of an Atom feed as it has a date, content, unique id,
Atom is getting adopted by big names such as for example Google for many of their public APIs (GData)
"Don"t Invent XML Languages" - Tim Bray (http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages)