Date

27 Jun 2017

7am PDT

Meeting Link

https://www.uberconference.com/villagereach-isg

Optional dial in:
Dial in: 401-283-5773
PIN: 66343

Attendees

• Brandon Bowersox-Johnson

• Nikodem Graczewski
• Paweł Gesek
• Paweł Albecki
• Weronika Ciecierska
• Sam Im

Goals

• UI Extension Maintainability
  • What has worked for Malawi
  • What technical implementation

Discussion items

Notes

Malawi UI Development Notes

From Weronika Ciecierska (Unlicensed) (added notes from Nick Reid (Deactivated) in italics, he also reformatted the notes slightly ;-)

Branding changes

• Most of the branding work was done by Nick (from what I can remember, I was on leave for a week then) - I think it is quite simple and easy to do - it is enough to just add new scss files (and png files for logos) with the same names as in the core, and they will be overwritten.
• This is correct. In many places all it took was changing a SASS variable, such as changing $brand_primary.
• If the css selectors change, then the branding will fall off. 
• To better support maintainability, we should create a list of what we don't want to change. We could create tests to confirm that the selectors stay and are not changeable.
• We could create a sample repository for the standard branding specific changes.
  • What should be a "brandable" change?

One thing worth noting is that currently we don't have our own transifex account and we are storing json files with messages in the GitHub repository (there's a ticket to start using transifex for messages changes specific for Malawi).

Adding new functionality

• Adding new screens, new positions to the navigation bar etc. is really easy - we just need do add new files and after building UI we can see them. We can also write tests and the will be carried out together with tests from the core.

Changing existing functionality

• This is where it's getting a little bit messy. In most cases, directives/controllers/services were not written with extensibility/configuration possibilities in mind
• Usually we just have to copy the file from the core repository over to the Malawi repository and then change it the way we want.

Problems that I encountered because of this solution:

(1) Overwriting Unit Tests

At first, it wasn't possible to overwrite test files - so for example when a controller file was copied to the Malawi repository and then its functionality was changed, we could create new tests for it, but the old tests were also carried out while build - there was no possibility to overwrite/remove the core tests.

We wanted to be sure, that implementer won't break existing functionality when adding/editing files. Later we changed our approach, and right now it's possible to overwrite tests, because some of the tickets were changing tested functionality in a way that was intended, but was breaking the core tests.

For example: in the core, requisition with status IN_APPROVAL is editable for the approver, and in the Malawi implementation it's read-only - our change was breaking the product grid tests checking "isReadOnly" method.

(2) Maintaining Forked Files

After every release, I had to go through all copied files in the Malawi and manually merge in the changes that happened in those files in the core since the latest release. Sometimes it was only refactor, sometimes it was changed functionality.

At the beginning it was quite easy task to do, but merging this month's release was a little bit more complicated. Example: As mentioned in (1), we changed the "isReadOnly" method from the product grid. In the latest release the core team refactored this method (functionality was still the same) - so when merging those changes, I remembered that I changed this method in the forked file and merged it correctly, but if I weren't working on it before, I probably wouldn't notice this small change and just copy the new, refactored function to the forked file (on the other hand, that would make our overwritten unit tests fail and make developer realize that this functionality was changed in the Malawi implementation).

Question: What are the main reasons for forking the unit tests? When we added the Rejected status to the requisition service. The product grid had a new state that it needed to support but it didn't know about it. The new rendering state broke the unit tests.

(3) No Git History

There is no git history for the forked files - so we don't know which files are new and which are copied from the core repository. Additionally, we don't know what was changed in the files copied from the core - once I had to use online files comparator to determine what was different in the forked file.

The easiest solution for this is just add files from the core with two commits: first commit with the original file and THEN changes made in this file for the Malawi implementation in the next commit. Maybe it is possible to get git history of the files when we move Malawi repos to the different organization? This would probably be solved by using a second organization on github and forking repositories that are getting "functional changes"

UI Extension Maintainability

• Branding changes
  • Good
  • Currently undocumented — changing in OLMIS-???? by making template where OpenLMIS branding is separate, forkable, repository
• Adding new functionality
  • Good
  • Have yet to see if features can be meaningfully maintained
• Changing existing functionality
  • Not Good
  • Malawi implementation was unique because it was inside same github organization
    • it didn't fork larger repos so git could track changes and pull requests
  • File forking was intended for HTML markup changes
    • Pattern borrowed from Django framework

    • Q: Is markup maintenance a reasonable responsibility?

  • Large (important) files, such as RequisitionService, shouldn't be forked
    • Makes meaningless commit
    • Have to merge in changes from original project
    • Overwriting unit tests is a little nuts
    • Are these files too big?
  • AngularJS Decorator
    • Wraps methods of function
    • Can preserve original unit tests and 'changed' unit tests
    • Doesn't have access to internal object functions or state
    • Needs documentation in UI Extension Guide AND working examples

Improving UI Experience

• Extension Directive (ticket is rated 21 story points, without implementing in codebase) — too expensive?

Action items

• Define brand-able areas, extension points, and unit tests
• Define lighter UI extension mechanisms
  • See what can be borrowed from other projects
  • Pentaho XML decorators
  • Circulate UI Extension guidelines
• Implement proof of concept version of OLMIS-1682
  • See how MW implementation would be done