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
_______________________________________________ Yale CAS mailing list [email protected] http://tp.its.yale.edu/mailman/listinfo/cas
