What version(s) are we working on?

22 views
Skip to first unread message

Josh Zamor

unread,
Mar 27, 2017, 6:53:29 PM3/27/17
to OpenLMIS Dev
Hi all,

I've been out of town for a week and being removed from the daily updates for that week has highlighted an area that I think we still need to improve on:  communicating to the community which version a component (service, library or UI) that the community is working toward.

We all know that the next release of the Reference Distribution is 3.0.1.  I think this is communicated quite clearly, so no change needed here.

For any component though lets look at an example.  Currently the Reference Data Service is working on version 3.0.1 (of Reference Data Service - this version is not for the Reference Distribution version).  How do I know this?  The authoritative section for the version that a Service is currently working on is in each git repository as gradle.properties (for UI it's called version.properties).

For Reference Data Service, the gradle.properties currently reads:

######################################################################
# Name of the service and group that is responsible for it
######################################################################
serviceGroup=org.openlmis
serviceName=openlmis-referencedata

######################################################################
# Current version of the service
# Only a Release Manager should update this
# See https://openlmis.atlassian.net/wiki/display/OP/Rolling+a+Release
######################################################################
serviceVersion=3.0.1-SNAPSHOT

The last block, for serviceVersion, reads 3.0.1-SNAPSHOT.  This means that this service is working toward version 3.0.1, and any current builds are SNAPSHOTs as we work toward a release of 3.0.1.

However, if I look at the last release of Reference Data Service, 3.0.0, and look at the commits in-between 3.0.0 and the current HEAD, I see things which change the API in breaking ways (User's search endpoint is paginated for example).  By Semantic Versioning, a breaking API change is not a patch release.  Rather Semantic Versioning states:


Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.


So I would expect commits which break the API, would belong to a Reference Data Service whose serviceVersion read 4.0.0-SNAPSHOT.  Clearly that's not what we've done so far, which is confusing to stakeholders - including myself as a week-long absentee Reference Data Service component lead.

What I would have expected, and encourage us to start working this way from now on, is that over the past month since the release of Reference Data 3.0.0 at-least one of the following should have occurred:
  • The component lead has set-out that Reference Data Service is working toward a 3.0.1 Release, and therefore by Semantic Versioning, only non-breaking bug-fixes should have been worked on.
  • A discussion would have started on the developer forum calling for the community to move toward working on a different version, such as 4.0.0.  The breaking change wouldn't be committed to master until the component lead agreed and the serviceVersion was incremented.  It would be up to the component lead and the community to decide if a 3.0.1 release would occur first, before new work was started.

I also like the idea of components keeping a simple change-log whose goal should be to communicate the different pieces of work happening at the MAJOR, MINOR, and PATCH levels for the next release.  The Requisition service has a great start to this.

Immediate next steps:

  1. Component leads should check to ensure that their current working version, is the version they intend to release in time for the 3.0.1 Reference Distribution release in a few days time.
  2. Developers should check the serviceVersion of their component, and verify that any work they're working on, or have committed, is appropriate according to the next component release version and the rules of Semantic Versioning.  If there's work that needs to be done that doesn't agree with the serviceVersion, notify the component lead by posting to the developer forum (this one).

I'm open to further discussion here - what else do we need to make this process, and our intentions with individually versioned and released services, do we need for clarity among all developers and stakeholders in our community?


(Additionally the next time I'm leaving town for a week, I'll be sure to broadcast that more widely)

Brandon Bowersox-Johnson

unread,
Mar 27, 2017, 6:58:18 PM3/27/17
to OpenLMIS Dev

I like the plan Josh suggests. As we release our components this week, the component leads should help coordinate which snapshots we will be working towards next.

 

Here is the draft CHANGELOG that we are compiling to prepare for the 3.1.0 release of Requisition service (probably releasing this component Tuesday):

https://github.com/OpenLMIS/openlmis-requisition/blob/master/CHANGELOG.md

(It has a simple Markdown format. For the simple tickets, I copied from the Git commit history. For more complex tickets, I summarized what changed in the Requisition component.)

 

-Brandon

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/6ad4945d-4bb9-446b-9b49-347a7d991dcd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Paweł Gesek

unread,
Mar 28, 2017, 5:03:28 AM3/28/17
to openlm...@googlegroups.com
Hello,

the pagination was added recently and it was a hanging discussion for a while, see here:

https://openlmis.atlassian.net/browse/OLMIS-2143

I believe it was suggested in the ticket to do 3.1.0, but you are now saying that we should go with reference data 4.0.0, is that correct?

I think we are missing component versions on Jira. It would help organizing things if we could mark tickets for ref-distro version X.X.X, while also setting the component version Y.Y.Y. Currently it's hard to keep track of where we are going with these versions - ref distro 3.0.2 might bring us reference data 5.0, it might not. I think marking a component version on a ticket would also help in thinking about the potential breaking changes it is making.

One of the problems we faced during this sprint was picking up tickets that introduce or potentially introduce API breaking changes. It was unclear for us whether we want to find a way of doing these changes with backward compatibility (which may introduce redundancy) or just go for the next major version. It was an issue I raised I think in three different tickets - pagination, GS1 renames, auth-refdata dependency reversing. I think putting a component version on these tickets ahead of picking them up would make us think about the implications sooner and would help avoid these tickets getting blocked, while we are under pressure to release at the end of the sprint.

Regards,
Paweł

For more options, visit https://groups.google.com/d/optout.

--

Paweł Gesek
Technical Project Manager
pge...@soldevelo.com / +48 690 020 875

SolDevelo Sp. z o. o. [LLC]
Office: +48 58 782 45 40 / Fax: +48 58 782 45 41 Al. Zwycięstwa 96/98 81-451, Gdynia
http://www.soldevelo.com

Place of registration: Regional Court for the City of Gdansk KRS: 0000332728, TAX ID: PL5862240331, REGON: 220828585, Share capital: 60,000.00 PLN

Josh Zamor

unread,
Mar 28, 2017, 12:50:03 PM3/28/17
to OpenLMIS Dev
Thanks Pawel for the link to that specific ticket.  Clearly the "hanging conversation" isn't ideal.

I think the idea of adding a "component fix version" to JIRA issues is a good one, however in this case, and I expect many more we are to face soon, we already have enough information to make a quick and more-appropriate decision.

I believe we already had enough information to curtail the discussion that occurred in OLMIS-2143, and here's why:
  1. I as the component lead set forth that Reference Data Service was working toward a 3.0.1 release by setting the serviceVersion (again, not talking about the reference distribution here).  By Semantic Versioning, working on this PATCH release means:

  1. PATCH version when you make backwards-compatible bug fixes.
  2. I as part of the backlog grooming also very likely knew about and "signed off" on work to commence on OLMIS-2143.
If I were the engineer picking up this ticket, and I saw the Component lead do both of those things, I too would be confused, however by way of the serviceVersion being set to a PATCH release, I would already know:

  1. We're aiming toward a PATCH release, so while there's no way I could implement this new feature in a PATCH release, I probably would prefer an implementation that is a MINOR release over an implementation that is a MAJOR release.
  2. Knowing that we're not working on a PATCH release, I'm blocked working on this ticket until the component lead moves the serviceVersion to either working on a MINOR or MAJOR patch release.  To do this we had some good discussion in the ticket, which is good, though our options should have been driven by the serviceVersion.
  3. The component lead may want to wrap up the work that's gone into the PATCH release, and release it, before moving on to working on the next version.  This really needs to surface in the technical forum.

So at the time of grooming, at the time of working on the JIRA issue, we already had enough information on what we're working toward, we just had to have the conversation around the serviceVersion, when(if) the PATCH release was going to be released, and then a decision on when work on the next (MAJOR or MINOR) release would start.  As I outlined, I'm now calling for these discussions and announcements to occur in the technical forum.

The point here isn't to call out what was done "wrong", more to point out that we already had tools and procedure to frame our decision making:
  1. Components are Semantically Versioned.  If anyone doesn't know this front-to-back, print it out and read it at the start of everyday.  It's a requirement for all engineers and component leads.
  2. The serviceVersion in gradle.properties (or version.properties in the UI components), lay out what release the lead and the developers of that component are working toward.  If a ticket needs to be worked on as soon as possible that doesn't agree with the serviceVersion, then the component lead needs to weigh in.  If a version is going to be released or a new version will be started, I want it announced as it's own thread on the technical forum.

Beyond these tools and process, there is a tension underlying our decisions:

  • Making new releases that don't break actual clients (here we need to know which implementations are using which components - and ideally the endpoints they're using)
  • Building new functionality and doing things in a better way.

At this point I feel that while we need to demonstrate to the broader community that we can release stable software, it's also the point in time to make breaking changes as we don't yet have a lot of implementations building clients off of our public API.  That said these decisions can't be made in the depths of a ticket, so again I'm calling for us to start having these discussions here in the dev forum.


Are we in agreement about the immediate next steps?


  1. Component leads should check to ensure that their current working version, is the version they intend to release in time for the 3.0.1 Reference Distribution release in a few days time.
  2. Developers should check the serviceVersion of their component, and verify that any work they're working on, or have committed, is appropriate according to the next component release version and the rules of Semantic Versioning.  If there's work that needs to be done that doesn't agree with the serviceVersion, notify the component lead by posting to the developer forum (this one).


To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev+unsubscribe@googlegroups.com.

To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/EF996AA1-E727-4A6F-BCED-9DD356109C78%40villagereach.org.
For more options, visit https://groups.google.com/d/optout.

Paweł Gesek

unread,
Mar 28, 2017, 1:23:41 PM3/28/17
to openlm...@googlegroups.com

Hello,

yes, I believe the component leads have done that. We will move discussions about this to the forum and away from channels such as Slack. I will assist them with these new responsibilities of controlling the component versions.

As for the approach, I believe this will now require more communication between the component leads and the product owner. The versioning approach is sound, however holding off some tickets until a PATCH version is completed and dev forum discussion about versions end, might impact when these tickets are be able to get completed - and these tickets might have been marked as *MUST* for the ref distro release that is coming at the end of the sprint.

I still think think that we would want to know the potential backward compatibility issues a bit sooner and avoid finding them half-way through a sprint - there is overhead in time with these discussions on the dev forum and rolling out a patch release, and our release cycle is relatively short nowadays. I think we are at fault for not recognizing these issues during planning - we will pay more attention to them in the future and try to act on them sooner.

Regards,
Paweł
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.

To post to this group, send email to openlm...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

Brandon Bowersox-Johnson

unread,
Mar 28, 2017, 1:29:38 PM3/28/17
to openlm...@googlegroups.com

I suggest on the Grooming wiki pages—where the Product Owner prioritizes tickets for upcoming sprints—that we add a note about which component version we are working towards.

 

For Requisition component I’ve added this at the top for the coming sprint:

https://openlmis.atlassian.net/wiki/display/OP/Backlog+Grooming+Sprint+23

“Requisition

We expect version 3.1.0 will already have been released around Tuesday, March 28. After that, we will proceed with 3.1.1-SNAPSHOT to do bug fixes, performance, security, & refactoring.”

 

That way there will be awareness as we conduct group planning activities. That would have helped us catch the mis-match that Josh described.

 

-Brandon

To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.

Reply all
Reply to author
Forward
0 new messages