Hi Developers / Committers,
As mentioned in yesterday's developers meeting, I'm calling
a public VOTE around whether we include the Services API
refactoring in the upcoming DSpace 6.0 release. As this
change constitutes a major code refactor of the "dspace-api"
(DSpace Java API), we'd appreciate feedback from anyone on
this direction for 6.0. (If you have not yet read about the
Services API refactoring, a brief summary and links to more
information is provided at the end of this email)
Please VOTE with one of these three options:
+1 = "I agree. We should include Services API
refactoring in 6.0"
0 = "I'm undecided / unsure" (Please provide a reason)
-1 = "I disagree. The Services API refactoring should
NOT be included in 6.0" (Please provide a reason why
you disagree)
Per our Voting Procedures [1], a vote on code modifications
requires: "at least three positive (+1) votes, and no
negative votes (-1) to pass. In this scenario, a negative
vote constitutes a 'veto'." While /anyone/ is welcome to
vote, only Committers have "binding" votes (and can cast a
veto). Others are free to vote to express your opinion, but
those votes are considered advisory in nature.
This public vote will be open until *15:00 UTC (11:00am EDT)
on Wednesday, August 12* (which is the time of our next
Developer Meeting).
If there are any questions, feel free to ask them on this
thread.
*Summary of Services API refactoring*
The Services API refactoring is a major refactoring of the
"dspace-api" (DSpace's Java API) to better support
"separation of concerns/responsibilities". Simply put,
often, in the existing API, there is an intermingling of
business logic and database logic which is difficult to
maintain, debug and/or build against. One of the most
obvious examples is how we deal with database software
support (PostgreSQL vs. Oracle), but such intermingling of
logic exists in many of our core classes. The DSpace
"Services API" attempts to tease apart the database logic
from the business logic into separate layers, while also
adding support for Hibernate (http://hibernate.org
<http://hibernate.org/>). The goal is to provide an easier
to maintain, more modular API, while also enhancing how we
deal with database logic in general (via Hibernate).
Much more information with documentation,
tutorials/examples, and a video presentation at:
https://wiki.duraspace.org/display/DSPACE/DSpace+Service+based+api
What does adding this refactor to 6.0 mean?
* This is essentially a *new* Java API for DSpace. But,
it performs a very important refactor (see "Pros" below).
* It is not backwards compatible with the existing API.
All developers and Committers who work with the Java API
will need to learn this new API, as all future
development will require using this Java API.
o Committers will be expected to learn, use and
support this API immediately. @mire will be
providing additional training materials / examples
to help everyone get up to speed.
o We also will need immediate help from Committers (or
other volunteers) to refactor and test all other
modules within DSpace. Currently, only the XMLUI has
been refactored to support this new API. All other
modules (JSPUI, OAI, REST, RDF, SWORD, etc) will
need similar refactoring as soon as possible.
* If this refactor is voted in, Committers will
immediately do the following:
o The "master" branch will be temporarily frozen.
We'll ask for no new changes until this API can be
merged (PRs can still be created, but we will
refrain from merging them)
o We'll start a new (temporary) feature branch (under
DSpace/DSpace) based of latest "master" and merge
the existing Services API code there.
o We'll then rapidly work together to refactor and
test all other modules based on the new API. (If we
work as a team, the goal would be for this process
to only take a few weeks)
o Once everything is refactored against this API and
passes our Unit Tests, the Services API code will be
merged into "master". At this point, "master" will
be unfrozen, and we can again merge in PRs for the
6.0 release.
PROS to adding to 6.0:
* It modularizes our primary API in a way that makes it
much easier to achieve future goals on our Roadmap [2]
(especially, moving us towards potentially better
support of third-party modules)
* It cleans up one of the "messiest" areas of our existing
API, the Database management / hardcoded Oracle and
PostgreSQL queries, in favor of using Hibernate. This
allows us the potential to support additional database
platforms in the future (e.g. MySQL or similar). It
decreases the likelihood of Oracle-specific bugs (which
have always been a problem), as the Oracle queries are
delegated to Hibernate. It also simplifies the process
of testing for database-specific problems in general (as
again, all queries are delegated to Hibernate).
* It begins teasing apart a true "business logic layer" in
the API (see the "service layer" of this new API)
* The API itself will not affect the fresh installation or
upgrade process of DSpace 6.0, provided that you have
not made local changes that rely on the existing Java
API (dspace-api). If you have made such local changes,
the refactor process should not be difficult, but it
will be necessary before you can successfully upgrade to
6.0.
CONS:
* It is not backwards compatible with the existing Java
API. Again, anyone who has made customizations that rely
on the Java API (dspace-api) may need to refactor their
local customization. But, we believe that vast majority
of institutions (likely 90% or more) should not
experience any upgrade difficulties, as most only make
customizations to the theme / look and feel of either
the XMLUI or JSPUI.
* As it is not backwards compatible, this does mean that
existing PRs (Pull Requests) reliant on the Java API may
need refactoring/rebasing. Unfortunately there's no easy
way around this, but examples already exist in the
documentation (see wiki page linked above) showing how
to perform common tasks via the new API.
* As this is a major change, it could affect our 6.0
timelines unless we can work together to quickly get
this change merged and tested. The quicker the merge
process occurs, the more rapidly we can stabilize
everything (and refactor existing PRs as needed).
[1]
https://wiki.duraspace.org/display/DSPACE/Developer+Voting+Procedures
[2] https://wiki.duraspace.org/display/DSPACE/RoadMap
--
Tim Donohue
Technical Lead for DSpace & DSpaceDirect
DuraSpace.org <http://DuraSpace.org> |DSpace.org <http://DSpace.org>
|DSpaceDirect.org <http://DSpaceDirect.org>
