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 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 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
[...]
|
begin:vcard
fn:Adam Rybicki
n:Rybicki;Adam
org:Unicon, Inc.;Professional Services
adr:Suite 113;;3140 North Arizona Avenue;Chandler;AZ;85225;United States
email;internet:[EMAIL PROTECTED]
tel;work:+1-480-558-2400
tel;home:+1-310-265-8286
tel;cell:+1-310-980-2758
x-mozilla-html:FALSE
url:http://www.unicon.net/
version:2.1
end:vcard
smime.p7s
Description: S/MIME Cryptographic Signature
_______________________________________________
Yale CAS mailing list
[email protected]
http://tp.its.yale.edu/mailman/listinfo/cas
