Jason Dobies wrote:
Brad Buckingham wrote:
Brad Buckingham wrote:
Miroslav Suchý wrote:
<http://git.fedorahosted.org/git/?p=spacewalk.git;a=commitdiff;h=c55ad4bf0952843b458b33579544338069cb442e>
May I ask that with new API addition/change we bump minor number of
web.apiversion in file web/conf/rhn_web.conf
And in Javadoc we write comment similar to:
Available since API version 10.1
Mirek,
Thanks for the suggestion. Sure, I'll commit a change today.
Brad
_______________________________________________
Spacewalk-devel mailing list
[email protected]
https://www.redhat.com/mailman/listinfo/spacewalk-devel
Team,
I updated the API doclet that is used to generate our API docs to
support the javadoc '@since' tag. As a result, when adding a new API
or modifying the signature/return of an API, if you add this tag, it
will reflect the version in the generated API documentation.
For example, the following is the 'code' for the listSnapshotPackages
API:
/**
* list the packages for a given snapshot
* @param sessionKey key
* @param snapId snapshot id
* @return Set of packageNEvra objects
* @since 10.1
*
* @xmlrpc.doc List the packages associated with a snapshot.
* @xmlrpc.param #session_key()
* @xmlrpc.param #param("int", "snapId")
* @xmlrpc.returntype
* #array()
* $PackageNevraSerializer
* #array_end()
*/
From this, the following API doc will get generated:
Method: listSnapshotPackages
Description:
List the packages associated with a snapshot.
Parameters:
* string sessionKey
* int snapId
Returns:
* array:
o struct - package nvera
+ string "name"
+ string "epoch"
+ string "version"
+ string "release"
+ string "arch"
Available since: 10.1
cheers,
Brad
_______________________________________________
Spacewalk-devel mailing list
[email protected]
https://www.redhat.com/mailman/listinfo/spacewalk-devel
Very cool. Where does the actual number "10.1" come from? Is it
incremented for each Spacewalk release? How does that fit into
potential changes to the API now in terms of the version number in
Vader v. Spacewalk? Granted, the last scenario probably shouldn't be
happening, but figured I'd throw it out there.
Just a quick reply. A few months ago, web.apiversion was added to the
/etc/rhn/default/rhn_web.conf. The initial value given to that was
10.0. This API version is intended to be independent/separate from the
Spacewalk version, hence the reason a value such as 10.0 was chosen.
My understanding is that the intent is to update this version under the
following scenarios:
1. bump major value on each Spacewalk version (so in Spacewalk 0.6, we
should bump to 11.0)
2. bump the minor version as we add new APIs or alter the
signature/return value of an API
Folks, please let me know if this is not aligned with previous thoughts.
Unfortunately, as Mirek pointed out this morning, we have not done a
very good job at tagging APIs as the are introduced or updating this
version when those changes occur. (I know I am guilty of that, but hope
to improve :) )
Hope this helps,
Brad
_______________________________________________
Spacewalk-devel mailing list
[email protected]
https://www.redhat.com/mailman/listinfo/spacewalk-devel
