Interact with Changes

Version 25 by Steve Luo
on Jun 13, 2011 06:54.

<< Changes from 24 to 25
compared with
Version 26 by Steve Luo
on Jun 13, 2011 09:18.

Changes from 26 to 27 >>
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 15 changes. View first change.

 {panel:title=TOC|titleBGColor=#F7D6C1|bgColor=#FFFFFF}
 {toc:style=disc|indent=20px}
 {panel}
  
 Since QuickBuild 4.0, you can retrieve changes via RESTful APIs. The base URI for changes RESTful APIs is:
 {code}
 /rest/changes
 {code}
  
 h3. List all supported APIs
 ||URI||Response Type||Params||
 |/rest/changes/help|_text/html_| |
  
  
 h3. Get the data version of changes
 ||URI||Response Type||Params||
 |/rest/changes/version|_text/plain_| |
  
 h3. Get the commit stats
 ||URI||Response Type||Params||
 |/rest/changes/stats/\{configuration}|_text/xml_| * *configuration*
 Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix *PATH:*, for example, _PATH:root/My/DEV_
 * *build*
 Specify the build id you want.
 * *from_build*
 Specify the from build when finding changes in a build range.
 * *to_build*
 Specify the to build when finding changes in a build range.
 * *from_date*
 Specify the from date when finding changes in a build range.
 * *to_date*
 Specify the to date when finding changes in a build range.
 * *date_pattern*
 Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
 * *repository*
 Get the changes only in a specific repository.
 * *committer*
 Get the changes only committed by the specified committer|
  Get the changes only committed by a specified committer|
  
 *Query stats of a specific build*
 {code}
 http://quickbuild:8810/rest/changes/stats/25?build=102
 {code}
  
 the response looks like:
 {code}
 <stats commits="5" modifications="7" added="2" modified="3" deleted="2"/>
 {code}
  
 *Query commit stats in a build range*
 {code}
 http://quickbuild:8810/rest/changes/stats/25?from_build=100&to_build=120
 {code}
  
 *Query commit stats in a date range*
 {code}
 http://quickbuild:8810/rest/changes/stats/25?from_date=20110501&to_date=20110601
 {code}
 by default, the date pattern is _yyyyMMdd_, you can also specify the date pattern by adding parameter *date_pattern*, the valid date pattern can be found [here|http://download.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html], for example:
 {code}
 http://quickbuild:8810/rest/changes/stats/25?from_date=2011-05-01&to_date=2011-06-01&date_pattern=yyyy-MM-dd
 {code}
  
 *Query commit stats of a specific repository or committer*
 By adding _repository_ or _committer_ parameter, you can get the stats of a specific repository or committer, for example:
 {code}
 http://quickbuild:8810/rest/changes/stats/25?build=102&repository=mysvn
 {code}
  
 this will get the stats data for repository mysvn.
  
 h3. Data structure of the changes
 In QuickBuild, we use Changeset and Modification to represent a SCM commit. A changeset is an atomic collection of changes to files in a repository and it usually contains several modifications. A modification means developer made a specific action to a file when committed to a repository. In QuickBuild, the actions include:
 * ADD
 * MODIFY
 * DELETE
  
 The action in some SCM, for example, git, mercurial, have more actions, like rename, in QuickBuild, it will be speared into two actions, i.e. DELETE first, and then ADD, and maybe there are also other actions, QuickBuild will use MODIFY action to represent.
  
Below are meta data for changeset and modification:
  Below is the data structure of Changeset:
 {code}
<meta name="changesets">
  <column name="buildId" dataType="ID" isKey="true" />
  <column name="changeId" dataType="STRING" isKey="true"/>
  <column name="repository" dataType="STRING" isKey="true"/>
  <column name="commitDate" dataType="TIME"/>
  <column name="comment" dataType="BLOB"/>
  <column name="additional" dataType="BLOB"/>
  <column name="modifications" dataType="INTEGER"/>
  <column name="committer" dataType="STRING" /> <!-- Committer of the changeset -->
  <column name="userId" dataType="ID" /> <!-- QuickBuild user id, only valid when committer is also a valid quickbuild user -->
  <column name="added" dataType="INTEGER"/> <!-- Count of ADD action -->
  <column name="modified" dataType="INTEGER"/> <!-- Count of MODIFY action -->
  <column name="deleted" dataType="INTEGER"/> <!-- Count of DELETE action -->
 </meta>
 <meta name="modifications">
  <column name="buildId" dataType="ID" isKey="true"/>
  <column name="changeId" dataType="STRING" isKey="true"/>
  <column name="repository" dataType="STRING" isKey="true"/>
  <column name="fileName" dataType="STRING" isKey="true"/>
  <column name="edition" dataType="STRING" />
  <column name="previousEdition" dataType="STRING" />
  <column name="action" dataType="ENUM" values="ADD,MODIFY,DELETE" indexed="TRUE"/>
  <column name="pathType" dataType="ENUM" values="TEXT, BINARY, DIR"/>
 </meta>
  Changeset {
  String user; // committer
  Date date; // commit date
  String id; // change id
  String comment; // commit comment
  String repositoryName; // the repository name defined in QuickBuild
  repositoryType; // the repository type
  additional; // the additional information for a commit, for example, revision number for mercurial
  buildId; // the build this commit belongs to
  
  private List<Modification> modifications;
 }
 {code}
  
Changeset is related with modifications by below columns: buildId, changeId and repository. With those columns, you can search modifications for a specific changeset.
  data structure of Modification:
 {code}
 Modification {
  public enum Action {ADD, DELETE, MODIFY};
  public enum PathType {TEXT, BINARY, DIR};
  
  Action action;
  String path; // File path
  String edition;
  String previousEdition;
  PathType pathType;
  String additional; // Additional information of a modificaiton, for example, revision number for mercurial
 }
 {code}
  
 h3. Retrieve changesets
 ||URI||Response Type||Params||
|/rest/changes/changesets/\{configuration}|_text/xml_|* *configuration*
  |/rest/changes/\{configuration}|_text/xml_|* *configuration*
 Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix *PATH:*, for example, _PATH:root/My/DEV_
 * *build*
 Specify the build id you want.
 * *from_build*
 Specify the from build when finding changes in a build range, must be specified with to_build.
 * *to_build*
 Specify the to build when finding changes in a build range, must be specified with from_build.
 * *date_pattern*
 Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
 * *from_date*
 Specify the from date when finding changes in a build range.
 * *to_date*
 Specify the to date when finding changes in a build range.
 * *repository*
 Get the changes only in a specific repository.
 * *committer*
 Get the changes only committed by the specified committer.
 * *offset*
 Specify the first record when iterate the records, by default, the offset is 0.
 * *limit*
 Specify the number of total records you want to retrieve, by default, the limit is 50.
 * *asc*
Boolean type, specify the order by commit date ascendent or descendent, by default, it is false.|
  Boolean type, specify the order by commit date ascendent or descendent, by default, it is descendent.|
  
 *Query the changesets of a build*
 {code}
http://quickbuild:8810/rest/changes/commits/19?build=102&offset=10&limit=20
  http://quickbuild:8810/rest/changes/19?build=102&offset=10&limit=20
 {code}
  
 the response looks like:
 {code}
<report name="changesets" version="0.0" locale="en_US">
  <row ID="10" buildId="320" changeId="f090cd04725c5551f8a439fe0a53591193ea79c3" repository="hg" commitDate="2011-05-31T03:45:55.000+08:00" modifications="1" committer="steve" userId="2" added="1" modified="0" deleted="0">
  <comment><![CDATA[some comments]]></comment>
  <additional><![CDATA[ 13 ]]></additional>
  </row>
  <row ID="11" buildId="320" changeId="f090cd04725c5551f8a439fe0a53591193ea79c3" repository="hg" commitDate="2011-05-31T03:45:55.000+08:00" modifications="1" committer="steve" userId="2" added="1" modified="0" deleted="0">
  <comment><![CDATA[some comments]]></comment>
  <additional><![CDATA[ 13 ]]></additional>
  </row>
  <list>
  <changeset>
  <user>steve</user>
  <date>2011-06-03T15:11:40.000+08:00</date>
  <id>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</id>
  <comment>
  Fix TST-23: 2-phase load components
  </comment>
  <repositoryName>hg</repositoryName>
  <repositoryType>Mercurial</repositoryType>
  <additional>14</additional>
  <buildId>321</buildId>
  
  <modifications>
  <modification>
  <action>MODIFY</action>
  <path>Test.java</path>
  <edition>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</edition>
  <previousEdition>f090cd04725c5551f8a439fe0a53591193ea79c3</previousEdition>
  <additional>14</additional>
  </modification>
  <modification>
  <action>MODIFY</action>
  <path>big.java</path>
  <edition>913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943</edition>
  <previousEdition>f090cd04725c5551f8a439fe0a53591193ea79c3</previousEdition>
  <additional>14</additional>
  </modification>
  </modifications>
 </changeset>
  
  ... ...
</report>
  </list>
 {code}
  
 the format of commit date here is using [ISO8601 standard|http://en.wikipedia.org/wiki/ISO_8601]. The _additional_ column stores some extra information of the commits. For mercurial (hg) or bazaar, the _additional_ stores the revision no.
  
 *Query the changesets in a build range*
 {code}
http://quickbuild:8810/rest/changes/commits/19?from_build=10&to_build=20
  http://quickbuild:8810/rest/changes/19?from_build=10&to_build=20
 {code}
  
 *Query the changesets in a date range*
 {code}
http://quickbuild:8810/rest/changes/commits/19?from_date=20110501&to_date=20110601
  http://quickbuild:8810/rest/changes/19?from_date=20110501&to_date=20110601
 {code}
  
  
 *Query the changesets of a specific repository or committer*
 By adding _repository_ or _committer_ parameter, you can get the commits of a specific repository or committer, for example:
 {code}
http://quickbuild:8810/rest/changes/commits/25?build=102&repository=mysvn
  http://quickbuild:8810/rest/changes/PATH:root%2FMy%2FDEV?build=102&repository=mysvn
 {code}
 
 h3. Retrieve modifications
 ||URI||Response Type||Params||
 |/rest/changes/modifications/\{configuration}|_text/xml_|* *configuration*
 Specify the configuration. By default, specify configuration id here, if you want to specify a configuration path, you need add prefix *PATH:*, for example, _PATH:root/My/DEV_
 * *build*
 Specify the build id you want.
 * *from_build*
 Specify the from build when finding changes in a build range, must be specified with to_build.
 * *to_build*
 Specify the to build when finding changes in a build range, must be specified with from_build.
 * *date_pattern*
 Specify the date pattern when query by a date range, by default, the pattern is yyyyMMdd.
 * *from_date*
 Specify the from date when finding changes in a build range.
 * *to_date*
 Specify the to date when finding changes in a build range.
 * *change_id*
 Specify the change id you want to find.
 * *repository*
 Get the changes only in a specific repository.
 * *committer*
 Get the changes only committed by the specified committer.
 * *offset*
 Specify the first record when iterate the records, by default, the offset is 0.
 * *limit*
 Specify the number of total records you want to retrieve, by default, the limit is 50.
 * *asc*
 Boolean type, specify the order by commit date ascendent or descendent, by default, it is false.|
  
 *Query modifications of a build*
 Below example shows how to get the modifications for a specific build.
 {code}
 http://quickbuild:8810/rest/changes/modifications/10?build=120&offset=0&limit=20
 {code}
  
 the response looks like:
 {code}
 <report name="modifications" version="0.0" locale="en_US">
  <row ID="1" buildId="321" changeId="913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943" repository="hg" fileName="Test.java" edition="913fcbcdbe8f80d6c1fe5fce3bb49e1f0040a943" previousEdition="f090cd04725c5551f8a439fe0a53591193ea79c3" action="MODIFY" commitDate="2011-06-03T15:11:40.000+08:00" committer="steve" userId="2">
  <comment><![CDATA[Fix TST-23: 2-phase load components
 Fix TST-24: How are you?]]></comment>
  <additional><![CDATA[ 14 ]]></additional>
  </row>
  
  ... ...
  
 </report>
 {code}
  
  here, we use configuration path instead of configuration id.
 {note}
The columns: commitDate, committer, userId, comment which are columns in changesets are also included in the response so you may fetch the modifications directly instead of fetching changesets first and searching the modifications then.
   if you are using URL directly, you may need escape '/' to %2F
 {note}
  
 *Query modifications in a build range*
 {code}
 http://quickbuild:8810/rest/changes/modifications/10?from_build=100&to_build=200
 {code}
  
 *Query modifications in a date range*
 {code}
 http://quickbuild:8810/rest/changes/modifications/19?from_date=20110501&to_date=20110601
 {code}
  
 *Query the modifications of a specific repository, change id or committer*
 By adding _repository_ or _committer_ parameter, you can get the modifications of a specific repository or committer, for example, to search the modifications for change id 456, you can use below URL:
 {code}
 http://quickbuild:8810/rest/changes/modifications/25?build=102&repository=mysvn&change_id=456
 {code}