I'm still on vacation and its Friday night so I probably won't reply to any more of these emails until Tuesday ;-)
-Scott On Fri, May 16, 2008 at 7:39 PM, Scott Battaglia <[EMAIL PROTECTED]> wrote: > All, > > CAS already has a well-defined policy on removing, modifying, and replacing > publicly supported APIs. Unfortunately I can't locate the policy in our > wiki at the moment ;-) [or maybe its only in my head, which would make it > easier to change ;-)] Basically, we can deprecate publicly supported APIs > via minor releases and remove then in major releases (generally, with some > form of upgrade path, i.e. Services Management tool or Inspektr package). > Minor releases are defined as 3.0.x and major releases are 3.x. Again, > these policies apply to publicly supported APIs. As mentioned previously, > the old Services stuff and the Event stuff were unsupported code examples > used to demonstrate being able to support alternate/additional use cases in > the 3.0 release. > > I can also state that releases will most likely occur without complete > documentation for new features. We make a best effort attempt to document > anything major (as we did for 3.1 and 3.2), but most likely some of it will > be skeleton initially. We will not hold up a release because of it. We will > continue to answer questions on list as things pop up, and our volunteer > documentation coordinator (or myself, or others) translate that into > documentation as we can. Why do we do that? Because, the CAS team often > does not have dedicated time to work on the CAS software and works on it > when they can. Sometimes that time includes time to add additional > document and sometimes it doesn't. > > Documentation in the CAS wiki often contains whatever documentation people > are willing to contribute. Most of the documentation projects started with > 3.1 or later, which is why there is minimal 3.0.x documentation. 3.1 and > 3.2 are very similar in design (using Maven2, etc.), but you will see > sections of the documentation stating "if 3.1 do this, if 3.2 do this". > > We've often called for volunteers for documentation and gotten minimal > response. Through the heroics of a few people (I won't list names here as > I'll most likely forget to mention some), we've made great strides in our > documentation effort. However, as this thread indicates, more volunteers > are needed to further improve it. Only when we've got a good number of > people assisting with documentation efforts, would I consider a policy such > as the one Adam mentions about holding up a release until everything is > documented. We currently don't have the resources to implement that type of > policy and thus have an ad-hoc documentation policy. > > With the potential 4.0 release, we will hopefully revisit these questions > and have better answers as we solicit resources to help work on the project. > > -Scott > > On Fri, May 16, 2008 at 7:07 PM, Adam Rybicki <[EMAIL PROTECTED]> wrote: > >> Jonathan, >> >> Some simple-minded suggestions: >> >> - We should not remove an API unless it is a serious flaw that cannot >> be fixed internally. >> - APIs may be removed in major releases, but only if there is a >> documented migration path. >> - APIs may be flagged as deprecated in minor releases, and Sun's >> guidelines for When to >> Deprecate<http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/deprecation/deprecation.html#when>seem >> reasonable. >> - Newly released features, APIs, interfaces intended for developers to >> write to should have documentation and examples of usage. If they do not, >> the release does not happen. If the release inadvertently happens before >> the documentation is written, a major issue is logged in JIRA. >> - The documentation section on our Wiki should have release-specific >> "forks." We cannot afford to maintain the old release documentation, but >> we >> should not delete or overwrite older documentation because the newest >> version is out. We cannot assume that everyone has upgraded to CAS 3.2, >> uPortal 2.6, and I know we don't expect the entire world to be on uPortal >> 3.0 soon. There are so many institutions using CAS 3.0.x, and there is no >> place to find documentation for that version. >> >> I think that the uPortal project has done a pretty good job of that. The >> pains that Eric went through to assure compatibility and migration path to >> 3.0 bordered on heroic. The uPortal Release >> Strategy<http://www.ja-sig.org/wiki/display/UPC/Release+Strategy>document >> seems as valid today as it was when it was written. Personally, I >> would add a line that covers documentation expected for each release type. >> >> As you know, I have been to most JA-SIG conferences. ;-) The lack of >> documentation or the difficulty finding it is one of the most recurring >> themes I hear from new adopters of JA-SIG projects. >> >> Adam >> >> Jonathan Markow wrote: >> >> I would like to interject a few questions into this thread in hope of >> being helpful. Apologies in advance for my technical naivete on these >> matters. I'd simply like to see if we can a) arrive at a solution to the >> current problem that satisfies everyone, and b) avoid any future >> misunderstandings. >> >> It sounds like Adam was surprised to find that some API's he was counting >> on had disappeared in 3.2. I know that API's sometimes go away, but was >> this, in fact, a surprise, or had there been warning that this would happen? >> >> I know it's often a practice to deprecate stuff in a previous release. >> Had that happened in this case, or was there any other documentation that >> would have signaled the change? >> >> In any case, surprise or not, since Adam seems to have production code >> that has stopped working, does it make sense to restore the missing API's >> for now, with the understanding that it will be temporary, as the intent is >> to replace them with Inspektr, which offers many other advantages? >> >> Finally, can anyone suggest a practice that would help avoid similar >> misunderstandings in the future? >> >> Thanks, >> Jonathan >> >> [...] >> >> >> _______________________________________________ >> Yale CAS mailing list >> [email protected] >> http://tp.its.yale.edu/mailman/listinfo/cas >> >> > > > -- > -Scott Battaglia > PGP Public Key Id: 0x383733AA > LinkedIn: http://www.linkedin.com/in/scottbattaglia > -- -Scott Battaglia PGP Public Key Id: 0x383733AA LinkedIn: http://www.linkedin.com/in/scottbattaglia
_______________________________________________ Yale CAS mailing list [email protected] http://tp.its.yale.edu/mailman/listinfo/cas
