2017-04-18 Meeting note
- Josh Zamor
- Sebastian Brudziński
Date
7am PDT
Meeting Link
https://www.uberconference.com/villagereach-isg
Optional dial in:
Dial in: 401-283-5773
PIN: 66343
- note the changed dial in number and pin
Attendees
Goals
- Review options w/ adding features v sem ver
- Review Malawi Average Consumption extension proposal
Discussion items
| Time | Item | Who | Notes |
|---|---|---|---|
| 5m | Start | Josh |
|
| 25m | Review options with semver and Reference Data | Josh | |
| 30m | Review Malawi extension for average consumption | Sebastian Brudziński |
In a Reference Data system the major semantic version always goes up... now you know what's up
Situation
Reference Data was developed rapidly and is used by many other services. As those Services need to get data from Reference Data, there are more custom search endpoints for finding the right data as well as needs for the data to be returned paginated.
Concern
There has been some concern expressed that every release of Reference Data has been new major version, and this doesn't feel right.
Analysis
By Semantic Versioning, releasing a new major version designates to consumers of the public API that some part of it changed in a breaking way. For Reference Data this means the RESTful API. The most recent releases, v5 and v4, included:
- structural changes in the commodity model (unfortunately not all changes made it into the v4 release)
- users search endpoint was made paginated
- the Facility resource now supports the extension mechanism ExtraData, which pushes the Facility search endpoint from a GET operation to a POST operation
Of these, the structural change to the commodity model is the one that feels like it warrants the major version change - most everything uses the commodity model, and we've known we've wanted to make this change since before v3 was released, we just haven't gotten all of the change done in one major release, in part due to a quicker release cycle of Ref Distro.
Pagination and support for extra data however feel like we have some options.
Options
#1, Do the work, break the contract, and release as a major version
This option is the simplest for the component - we simply change the contract for the search endpoint and/or the pagination and we release the next major version of Reference Data.
| Pro | Con |
|---|---|
| Makes just the change/work that's needed | Breaks the contract, so the semantic version has to be increased, and all consumers have to do work to account for the change |
#2, Do the work, don't break the contract, and release a minor version
Both of the reason's we've identified (extra data and pagination) involve a breaking change to the search endpoint of a Resource. It follows that a new Search endpoint could be introduced that supports pagination as well as extra data's POST, while the old one is marked as deprecated yet retained.
| Pro | Con |
|---|---|
| Makes just the change/work that's needed | Consumers will eventually have to do the work when the deprecated operations are removed |
| Doesn't break the contract, consumers still work | Will have to maintain both endpoints while they both exist (fixing bugs, refactor?) |
We would think that we would phase out the deprecated operation in the next MAJOR release, though a set amount of minimum support time (e.g. 6 months) might be preferable.
#3, Do all the work NOW - and release the new major (uber) version
As it's name implies, it means that we should paginate all the Search endpoints, and add ExtraData to all of the current (about 22) Resources of Reference Data service.
| Pro | Con |
|---|---|
| Big bang - everything is fixed (we could more things) | Breaks the contract, so the semantic version has to be increased, and all consumers have to do work to account for the change - to all the resources |
| Ref Data service would be more consistent - cognitive load | Resource intensive - this scope of work may require a team (small) to go through and make all the changes. Also all other components may need more human resources |
| We may do work that's un-needed. Maybe supply lines will never need extra data. Stock adjustment reasons may go away, replaced with stock management service. | |
| We may not really prevent the major version from being incremented rapidly. |
Moving from GET to POST for search, and implementing pagination for search, could reduce people resources for making reference data better (maybe half the work). Consumer LOE would stay the same.
Malawi - Extension for average consumption
Average Consumption calculation - extension analysis
Some question about the LineItemFieldsCalculator calculations and the delegating class - feels weird to have both
How does the data get back to the UI?
- Is it an extension to the calculation class? Or an extension to getting previous requisitions? Or both?
- If it's just the previous requisitions, then if the configuration is the previous N years
Next steps:
- check to see if previous requisition approach (returning N in DTO) is feasible
- mature the document (specific ext approach, actions and timeline, containers and packaging) - ping technical forum
- tech comm to review future draft
Action items
- Josh Zamor to throw up voting for Reference Data poll of the forum (everyone votes by wed/thur)
- Sebastian Brudziński to continue maturing Malawi Ext. Proposal for Average Consumption. Post to technical forum for intermediate feedback
- Sebastian Brudziński to remind technical committee to discuss new draft document at next committee call (May 2nd)
OpenLMIS: the global initiative for powerful LMIS software