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.

Requirements

Definitions

CI System

TODO

Client

TODO

Build

TODO

Build category

This is equivalent to "project" in CC and "build plan" in Bamboo

Build status

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?)

Build result

failed, succeeded (build result can be sent on a running build if the CI system is capable of detecting failures before completion).

Namespace

The XML namespace for the Atom extensions is http://cifeed.sf.net/schemas/0.1

CI Feed Documents

CI Feeds has to comply with the Atom Syndication Format RFC 4287

ID

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.

Link

The link of each entry should point to the CI systems report for that particular build.

Ongoing builds

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.

Start/end time

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?

Feed level atom:updated

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.

Category

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.

Title/Summary/Content

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.

Modification

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).

Test information

Variants of feeds

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:

Compact

Does not include test and modification information.

Historical only

Does not include ongoing builds.

Ongoing only

Does only include ongoing builds and potentially the previous build. Many CI clients act based on the ongoing build and the previous build.

Multiple projects ("categories")

A CI system can provide variants that include multiple or all projects in the same feed.

Transport

This specification does not require any specific transport mechanisms, but we foresee that two forms of transport will be used.

Pull from client with HTTP GET

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.

Push from CI system with HTTP POST

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.

Security Considerations

TODO

Appendix A: RELAX NG Compact Schema

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?,
  }+,
}

Appendix B: Example

<?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>

Appendix C: FAQ

Why Atom?

Other options: Completely custom XML, RSS 1.0, RSS 2.0.