Kuali Rice Development
  1. Kuali Rice Development
  2. KULRICE-4505

Decide on and document guidelines for how service contracts, DTOs, and implementations should be versioned

    Details

    • Type: Task Task
    • Status: Closed Closed
    • Priority: Blocker Blocker
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.0
    • Labels:
      None
    • Similar issues:
      KULRICE-4508Decide on and document recommended practices for service governance
      KULRICE-4503Decide on and document process for how service contracts will be defined and maintained
      KULRICE-4510Decide on and document a standard for service names and namespaces and how they will be affected by versioning
      KULRICE-7564Guidelines on how to build Maintenance Documents
      KULRICE-4511Refactor service registry to implement inclusion of version numbers in the service registry
      KULRICE-4554Improve how "store-and-forward" services are implemented in respect to the service registry
      KULRICE-6039Document standards for JAXB and JAXWS annotations on Rice services and dtos
      KULRICE-5152Add version number to KRMS DTOs
      KULRICE-6034Document guidelines related to URL compatibility
      KULRICE-5231General cleanup and verification tasks for KEW version compatibility refactoring
    • KAI Review Status:
      Not Required
    • KTI Review Status:
      Not Required

      Description

      The method discussed in the meetings was a package-based approach where we create copies of everything (services and dtos) everytime (at most once per rice version though) we make a change to a service contract or it's dtos. Though I recently had some discussion with Jeff and Jason on how we might be able to make the developer experience here a little bit better using creative subclassing and factories.

      Some additional questions to answer here:

      1) When we create a new version of rice to do we always reversion all services or just on an "as-needed" basis?
      2) Should service versions align with rice version numbers or be independent?

        Activity

        Hide
        Eric Westfall added a comment -

        Here were some ideas that I had on trying to deal with versioning a bit more "automagically". After some conversations with Scott, Jason, and Jeff it sounds like this approach is probably not a good idea since it lends itself to some potentially undeterministic behavior moving forward and it's not very explicit either, which could probably lead to compatibility problems being introduced later down the road without an easy way to detect them beforehand.

        But for the sake of posterity, here is what I had originally proposed:

        The other part of what I’ve been thinking about here is how we handle versioning. I think what we discussed was essentially creating copies of everything as soon as a change needed to be made to the contract. I wonder if we can get around the frequency of having to do this a little bit and say the following:

        1) All generated wsdls will have a version number and all service endpoints will include a version number in the registry (and I believe we said we would also accomplish this through the namespace?). This is no different than what we discussed last week.
        2) The only changes which are allowed to be made to existing service contracts is the addition of new operations. Existing operations cannot be changed at all.
        3) The only changes which are allowed in DTOs is the addition of new fields (and possibly new types referenced from those new fields). Existing fields cannot be changed it all.
        4) If either of the above two cases needs to be violated, then we need a brand new service with a different name and a different set of DTOs or we need to make the change on a major revision change (i.e. 1.x to 2.x)
        5) As long as cases 2 and 3 hold true, then when the change is made, we generate a new copy of the wsdl and increment it’s version (as well as deploying a new service endpoint for that version).
        6) However, both the old version and the new version of the service use the same service interface (and possibly implementation class). Since we have only added operations and/or data elements, I think that aegis should be able to handle this binding whether it’s old to new or new to old version of the service and the dtos as defined in the wsdl. But someone can let me know if I’m crazy here

        This seems like a nice solution to me (assuming it will work) because we are essentially re-versioning the service each time at the WSDL level when we make a change, but we get to maintain some of the sanity down at the code level.

        Show
        Eric Westfall added a comment - Here were some ideas that I had on trying to deal with versioning a bit more "automagically". After some conversations with Scott, Jason, and Jeff it sounds like this approach is probably not a good idea since it lends itself to some potentially undeterministic behavior moving forward and it's not very explicit either, which could probably lead to compatibility problems being introduced later down the road without an easy way to detect them beforehand. But for the sake of posterity, here is what I had originally proposed: The other part of what I’ve been thinking about here is how we handle versioning. I think what we discussed was essentially creating copies of everything as soon as a change needed to be made to the contract. I wonder if we can get around the frequency of having to do this a little bit and say the following: 1) All generated wsdls will have a version number and all service endpoints will include a version number in the registry (and I believe we said we would also accomplish this through the namespace?). This is no different than what we discussed last week. 2) The only changes which are allowed to be made to existing service contracts is the addition of new operations. Existing operations cannot be changed at all. 3) The only changes which are allowed in DTOs is the addition of new fields (and possibly new types referenced from those new fields). Existing fields cannot be changed it all. 4) If either of the above two cases needs to be violated, then we need a brand new service with a different name and a different set of DTOs or we need to make the change on a major revision change (i.e. 1.x to 2.x) 5) As long as cases 2 and 3 hold true, then when the change is made, we generate a new copy of the wsdl and increment it’s version (as well as deploying a new service endpoint for that version). 6) However, both the old version and the new version of the service use the same service interface (and possibly implementation class). Since we have only added operations and/or data elements, I think that aegis should be able to handle this binding whether it’s old to new or new to old version of the service and the dtos as defined in the wsdl. But someone can let me know if I’m crazy here This seems like a nice solution to me (assuming it will work) because we are essentially re-versioning the service each time at the WSDL level when we make a change, but we get to maintain some of the sanity down at the code level.
        Hide
        Eric Westfall added a comment -

        Added Jeff as a watcher.

        Show
        Eric Westfall added a comment - Added Jeff as a watcher.
        Hide
        Jason Whaley (Inactive) added a comment -

        Copying and pasting an idea from irc://chat.freenode.net/#kuali-rice on how to make this a bit more sane maven wise:

        "idea for hopefully managing the potential explosion of annotated classes JAX-WS interfaces/impls/dtos... once they are in their in their own module, if we changed the artifactId of that version each time and made sure there were never any package name conflicts across versions, then we could basically just maintain one version in the source code base at a time and rely on maven to pull in the previous versions of them"

        This will work, but it needs to be agreed upon by other Rice devs if they think it's a good idea.

        Show
        Jason Whaley (Inactive) added a comment - Copying and pasting an idea from irc://chat.freenode.net/#kuali-rice on how to make this a bit more sane maven wise: "idea for hopefully managing the potential explosion of annotated classes JAX-WS interfaces/impls/dtos... once they are in their in their own module, if we changed the artifactId of that version each time and made sure there were never any package name conflicts across versions, then we could basically just maintain one version in the source code base at a time and rely on maven to pull in the previous versions of them" This will work, but it needs to be agreed upon by other Rice devs if they think it's a good idea.
        Hide
        Jason Whaley (Inactive) added a comment -

        "Though I recently had some discussion with Jeff and Jason on how we might be able to make the developer experience here a little bit better using creative subclassing and factories. " <--- there's a way to do this with factories such that your business logic code won't have to deal with the explosion of package names and DTOs. We'll save how to implement that for when we get entrenched in refactoring recommendations after the initial analysis is done.

        Show
        Jason Whaley (Inactive) added a comment - "Though I recently had some discussion with Jeff and Jason on how we might be able to make the developer experience here a little bit better using creative subclassing and factories. " <--- there's a way to do this with factories such that your business logic code won't have to deal with the explosion of package names and DTOs. We'll save how to implement that for when we get entrenched in refactoring recommendations after the initial analysis is done.
        Hide
        Jason Whaley (Inactive) added a comment -

        Recent drafts of the Savoir Tech recommendations document include a strategy for this in chapter 3.

        Show
        Jason Whaley (Inactive) added a comment - Recent drafts of the Savoir Tech recommendations document include a strategy for this in chapter 3.
        Hide
        Jason Whaley (Inactive) added a comment -

        Marking resolved - reopen if needed.

        Answers described in sections and 3.7, 4.4 of recommendations document. 3.7 describes code changes/refactorings. 4.4 describes versioning.

        section 4.4 -
        "It is recommended that, given Rice's previous and expected frequency of releases and that service interface changes are not expected to occur very often with Rice, that Rice adopt a versioning strategy by versioning services independently and DTOs independently. Rice, though its governance process described in section 4.3, should try to minimize the number of changes to any existing services and seek to minimize the impact of such service changes when needed. This will result in a minimum amount of duplication in the "api" modules described in section 3.6 as well."

        Show
        Jason Whaley (Inactive) added a comment - Marking resolved - reopen if needed. Answers described in sections and 3.7, 4.4 of recommendations document. 3.7 describes code changes/refactorings. 4.4 describes versioning. section 4.4 - "It is recommended that, given Rice's previous and expected frequency of releases and that service interface changes are not expected to occur very often with Rice, that Rice adopt a versioning strategy by versioning services independently and DTOs independently. Rice, though its governance process described in section 4.3, should try to minimize the number of changes to any existing services and seek to minimize the impact of such service changes when needed. This will result in a minimum amount of duplication in the "api" modules described in section 3.6 as well."
        Hide
        Jessica Coltrin (Inactive) added a comment -

        Closing since these items are now in the release notes.

        Show
        Jessica Coltrin (Inactive) added a comment - Closing since these items are now in the release notes.

          People

          • Assignee:
            Jason Whaley (Inactive)
            Reporter:
            Eric Westfall
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Structure Helper Panel