Hi all, Just fyi here is a link to the text that Greg quoted: http://opencast.jira.com/wiki/display/MH/Matterhorn+Release+Process+%28Wip%29
I'll share some thoughts from my end; after 1.1 came out we decided our REST doc subsystem needed some work, and we are indebted to Kenneth for doing this for 1.2. This necessitated some API changes. It's a tough balance between fixing bad API endpoints (as Ruben mentions), and keeping all API endpoints static for ease of integration (as Hank mentions), and on top of this new paradigms to our underlying system (e.g. requiring workflow IDs when ingesting lectures) sometimes force us to change endpoints. The goal with the wording in the release document above is to ensure that our contracts with third party systems are clear(er) with an explicit x.y.z version number. So a vendor can say something like "product P works with matterhorn 1.2" and be assured that 1.2.5 won't break that compatibility. Before launching into defining these rules more strictly, we would need a process which supports testing them. Pawel had some thoughts here, which I think are great. What I would prefer is a set of unit tests in trunk that compare trunk rest endpoints against other versions, perhaps similar to our test harness. With this, a release manager for maintenance releases could point the URL to a 1.2.0 server (or copy of those endpoints), and the tests would fail any time the syntax of the rest endpoints ends. The key here is making it easy on the RM, and abundantly clear to the devs when a rule has been broken. For the minor versions (the y in x.y.z), I'm afraid I'm at a bit of a crossroads in my thoughts. If we had a rule that the endpoints needed to be backwards compatible, 1.2 would have had to be 2.0. And I don't think that was warranted based on functionality. That being said, we might start out a bit sloppy with this because of the evolution of the project, I think things are a bit more solid now, though this might not be true for all components, Chris On Mon, 12 Sep 2011 16:07:13 +0200 Rubén Pérez <[email protected]> wrote: > Hi everyone, > > I cannot agree more with Hank. If I may add something more to the > discussion, the CA APIs are not RESTful at all, while some other APIs > changed their URLs months ago to comply with the standard as much as > possible. > > Another problem is that, while the "-api" java class has but a few > endpoints, the "-impl" class incorporates many more that are BASIC > for the CA's functioning but are not even reflected in the API. I > strongly believe this is a serious situation that must be addressed > asap, because it has been like this since I can remember, and we can > see the results: the CA is (arguably) the most problematic, bug-prone > piece of the Matterhorn software. My opinion is that these API issues > are the reflection of some structural and design problems that should > have been addressed at earlier stages of the development, but > unfortunately it was not done. > > If this debate leads to concrete #proposals to improve, fix, or > whatever task needed to make the CA better, I'm certainly willing to > work on that and help those demands come true. > > Best regards > Rubén > > 2011/9/12 Pawel Fic <[email protected]> > > > How about.... > > Creating a web page called "Matterhorn REST Enpoints". > > That will contain a detailed description of the API. > > > > Then figure out who is responsible for the project Matterhorn, and > > who decides if the API change is necessary - and this person would > > have to approve the changes to the spec. > > > > The difference between what the spec says and what the code does is > > bogus behavior of the code. > > > > A great start would be do document existing rest endpoints. > > For example I will have hundreds of "simple" questions like: > > what /capture-admin/recordings returns ? > > Other than a list of entires called "recordings" (what are > > recordings) that recently changed it's state. > > Usually: "<ns1:recording-state-updates/>" > > > > It is not important if API changed between Matterhorn 1.1, > > Matterhorn 1.2 or Matterhorn 2.0, 2.0.1 or 2.0.1b. > > > > I want to be sure that this change to API was necessary, and also: > > what the API calls do. Without this it will be really hard for > > third party engineers / companies / students to develop their > > capture agents/schedulers/confidence monitoring and integrate with > > Matterhorn. > > > > -Pawel > > > > > > > >> mismatched API's can become a serious headache. > > > > > > > > I can't find any documentation relating > > > (Adam/whomever: Perhaps this > > > > should be doc'd somewhere?) to this, but previous > > > discussion on list > > > > developed the following rules: > > > > > > > > Versioning system: X.Y.Z > > > > > > > > Within Z releases the API does not change. These > > > releases are bug fixes > > > > and security updates > > > > > > > > Within Y releases the API *may* change. These > > > releases can add, change > > > > or remove features, as well as introduce new bugs and > > > security holes ;) > > > > > > > > If you're dealing with a different X release then all > > > bets are off. We > > > > will probably rewritten everything in Python by that > > > point. > > > > > > > > In all seriousness, I know of at least two changes. > > > One was a CA state > > > > endpoint, and that was to fix a bug. The other is > > > the schedule download > > > > endpoint, and that was for a feature I believe. > > > > > > > > G > > > > > > > >> The capture agent world is no longer restricted to > > > the home-grown > > > >> do-it-yourself models, and the MH development > > > community needs to > > > >> recognize this. > > > >> > > > >> Hank > > > _______________________________________________ > > > Matterhorn-users mailing list > > > [email protected] > > > http://lists.opencastproject.org/mailman/listinfo/matterhorn-users > > > > > _______________________________________________ > > Matterhorn-users mailing list > > [email protected] > > http://lists.opencastproject.org/mailman/listinfo/matterhorn-users > > -- Christopher Brooks, BSc, MSc ARIES Laboratory, University of Saskatchewan Web: http://www.cs.usask.ca/~cab938 Phone: 1.306.966.1442 Mail: Advanced Research in Intelligent Educational Systems Laboratory Department of Computer Science University of Saskatchewan 176 Thorvaldson Building 110 Science Place Saskatoon, SK S7N 5C9 _______________________________________________ Matterhorn-users mailing list [email protected] http://lists.opencastproject.org/mailman/listinfo/matterhorn-users
