2.7 Deprecations

Whether for APIs or end-user functionality, deprecation should follow a general pattern of flagging and then allowing time for community adaptation. Only after an appropriate time has passed should the deprecated element be removed. The appropriate amount of time will be determined by the case, but a standard measure should be in terms of feature releases - eg. it may be flagged as deprecated for 2.7 and then removed in 2.8.

What counts as appropriate flagging may also vary with the case. Purely technical method deprecation may be handled in the code itself, but deprecation of user-facing functionality should be prominently flagged in the release notes and announced on-list. The deprecated functionality should be disabled by a configuration property that the local institution may override. If the deprecated functionality is an entire tool, it should simply be stealthed.

Deprecation decisions should be arrived at by consensus, and it will be the responsibility of the product council to document these outcomes or help forge this consensus where needed, though in matters of code maintenance the maintenance team should generally be deferred to.

Reasons for deprecation may include:

• The functionality or code is no longer maintainable, or there are outstanding critical or blocker issues and no community resource is able to help
• The functionality or code has been superseded by code or capabilities which meet the same requirements in an improved way (according to the consensus view), and the improvement has been demonstrated in production with a full release cycle

Deprecation decisions should happen during the same period in which new tools or capabilities are being considered for inclusion, and both before QA begins for a given release.

NB. If a blocker arises for a new capability during a QA cycle, and no one is available to fix it, the offending code may be simply removed. This is not deprecation.

Status Quo

The Reports and Warehouse tools are not necessarily linked, but together they serve the need to produce high-level reports of portfolio usage data across multiple sites. The tools are, by all accounts, difficult to use and maintain, and the consensus view is that a better long-term solution should be found.

The Reports tool suffers from unfixed blocker issues in the latest 2.7 testing. Community resource to resolve these issues and continue to maintain the tools has not come forward, while the maintenance team feels itself unable to address them.

Both of these tools have been provisional, and were never adopted as core tools.

Warehouse provides really only an API, and so can't be stealthed.

Proposal

Reports should be stealthed, and they should both now also be flagged for deprecation in the release notes. If community resource comes forward to fix and maintain them they may be restored to full service in a future version. If not, they may be removed entirely for 2.8, but this should also be used as an occasion to discuss and perhaps support alternatives.

Who would be affected

There are institutions using one or both of these tools in production (the known institutions include IU and RINET), and they would be affected by the blocker issues in any event, should they opt for 2.7.

Status Quo

Mailtool is seeing no active development or maintenance, and it has technical design issues that make it difficult to maintain (eg. rather than use Sakai's EmailService it creates its own). These issues were addressed by a second generation of the tool (renamed 'MailSender') now in contrib. Mailtool was listed as deprecated in the 2.6 release notes, and it was stealthed.

Proposal

Remove the project from svn .externals and eliminate it from the tag. When convenient migrate mailtool to contrib and eliminate it from trunk/2.7.x.

Who would be affected

For the last year or more it's been recommended that users of mailtool switch to the mailsender contrib tool instead. This is of course not a solution for those not able to deploy a contrib tool.

Status Quo

The original developers of this tool (from Lancaster U) can no longer maintain it, and in fact are maintaining an alternative to it in contrib instead.

Proposal

Stealth the tool and mark it as deprecated. It can be removed in a future version. Devise recommendations for if/how to replace it in 2.8, including migration paths where possible.

Who would be affected

The tool could of course be unstealthed by those who wished to continue to use it in 2.7. As yet there are not definite plans to replace it for 2.8, let alone what a migration path might be between it and whatever would replace it.

Status Quo

Profile 2 supersedes the original Profile tool. Profile 2 has already been made the default in 2.7 QA, with Profile 'classic' disabled, but some dependencies on Profile remain.

Profile 2 is actively maintained, with the backing of 3 institutions, while the original Profile tool has no one committed to it.

Proposal

Profile 2 will be the default profile tool in My Workspaces for 2.7, while the original Profile tool will still be available to be opted for, but will be listed as deprecated in the release notes. Dependencies on Profile classic in other tools (eg. Roster) will be removed by the maintenance team.

Documentation on how to configure to use Profile classic should also be included in the release notes, as this is not simply a matter of a stealth property. (maybe more prominently than release notes)

Who will be affected

The general consensus seems to be that few people rely on the very simple profile tool for any critical function, and a strong majority will prefer the improvements of Profile 2. Both tools continue to work with the same data, in any event, so either may be opted for.

Status Quo

This tool was listed as removed in the 2.6 release notes, but it's still there. Its continued presence looks like a simple oversight.

Proposal

Follow through on the tool's removal as advertised for 2.6.

Who will be affected

It would be surprising if anyone were.

Status Quo

There are homegrown Sakai utilities that duplicate third party open source libraries. They often have issues in the way they are implemented, occasionally even duplicating their own functionality. If a quality third-party library can meet the same need, there is little point in maintaining Sakai-specific versions.

Proposal

The redundant ones should be marked as deprecated. The maintenance team and others will judiciously replace them with open source libraries on a case-by-case basis. Some kernel utils will be updated to use the open source libraries by the maintenance team. The maintenance team will also communicate with the dev list about any changes, and update documentation to discourage the usage of deprecated kernel utils.

Who will be affected

Developers.

Status Quo

There are two elements at issue here:

• a JCR adaptor for Sakai's Content Hosting Service (CHS), which was intended to allow CHS to talk to a JCR repo. This is an experiment that has not been production hardened.
• a JCR Service that allows Sakai to access a JCR repo (ie. without going through CHS). It has been used in production at both Cambridge and NYU, where it has been ported to Xythos and supports a contrib tool. This service is disabled by default, but can be turned on with a configuration property.

Both are not being actively developed or maintained.

Proposal

Remove the JCR adaptor to contrib.

Deprecate the JCR Service in kernel-1.1 (ie. Sakai 2.7) and remove in kernel-1.2 (to contrib). Announce this decision with a deprecation alert and provide one or more reminders of JCR's impending removal during 2010, early 2011.

Who would be affected

No OOTB functionality would be affected, just those institutions who integrate with a JCR repo. At the moment, this seems to be only Cambridge and NYU.

Status Quo

Sakai has historically used a coding pattern called a 'static cover' that masks the internals of dependency injection. This can make things easier for new developers, but - without rehashing all the arguments - it is also fair to say it is controversial. In particular, it can complicate the writing of unit tests, and so it has a bearing on the maintainability of the code.

Even if there were consensus on whether static covers are a bad thing (in case it's not clear: there isn't), refactoring to remove them would place a burden on a great many tools, core and contrib.

Proposal

Static covers that already exist will be retained indefinitely, but deprecated, and core code (ie. trunk) will gradually be refactored not to use them.

Proposal B: As above, but without deprecating static covers, and continuing to develop them.

Who would be affected

Developers.