changes.
| {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_id}|_application/xml_| * *configuration_id* |
| Id of the configuration. |
| * *build_id* |
| The build id you want. |
| | |/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_id=102 |
| | 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 stats for a build range* |
| | *Query commit stats in a build range* |
| {code} |
| http://quickbuild:8810/rest/changes/stats/25?from_build=100&to_build=120 |
| {code} |
| |
| | *Query stats for a date range* |
| | *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 stats of a specific repository or committer* |
| | *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_id=102&repository=mysvn |
| | 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. Each changeset contains one or more modifications. Below are meta data for changeset and modification: |
| | 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 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" indexed="true"/> |
| <column name="comment" dataType="BLOB"/> |
| <column name="additional" dataType="BLOB"/> |
| <column name="modifications" dataType="INTEGER"/> |
| <column name="committer" dataType="STRING" /> |
| <column name="userId" dataType="ID" /> |
| <column name="added" dataType="INTEGER"/> |
| <column name="modified" dataType="INTEGER"/> |
| <column name="deleted" dataType="INTEGER"/> |
| </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 |
| String repositoryType; // the repository type, for example, Subversion, Mercurial, Git |
| String additional; // the additional information for a commit, for example, revision number for mercurial |
| Long buildId; // the build this commit belongs to |
| |
| private List<Modification> modifications; |
| } |
| {code} |
| |
| | Changeset is related with modifications by below columns: buildId, changeId and repository. |
| | 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_id}|_application/xml_|* *configuration_id* |
| The id of configuration. |
| * *build_id* |
| The id of a specific build. |
| | |/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_id=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]. Element additional stores some additional information of the commits. For mercurial (hg) or bazaar, the additional stores the revision no. |
| | 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 of a build range* |
| | *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 of a date range* |
| |
| | *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_id=102&repository=mysvn |
| | http://quickbuild:8810/rest/changes/PATH:root%2FMy%2FDEV?build=102&repository=mysvn |
| {code} |
| | here, we use configuration path instead of configuration id. |
| {note} |
| if you are using URL directly, you may need escape '/' to %2F |
| {note} |
| |
| | h3. Retrieve modifications |
| Normally, a changeset often contains one or more modifications, and a modification usually means a specific action to a file. 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. |
| |