[FOLIO-1040] Tidy and clarify shared raml-util and each raml-using repo Created: 29/Jan/18  Updated: 12/Nov/18  Resolved: 07/Sep/18

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: P3
Reporter: Adam Dickmeiss Assignee: David Crossley
Resolution: Done Votes: 0
Labels: ci, core, madrid, sprint31, sprint32, sprint33
Remaining Estimate: Not Specified
Time Spent: 1 week, 2 days, 3 hours, 15 minutes
Original estimate: Not Specified

Attachments: Text File compare-raml-util-2018042116.txt    
Issue links:
Relates
relates to MODLOGIN-28 Remove old copy of raml-util at 'raml... Closed
relates to MODPERMS-31 Remove copy of raml-util at 'raml-uti... Closed
relates to FOLIO-1220 Ensure that all necessary schemas are... Closed
relates to MODINVSTOR-45 Move RAML and JSON Schema definitions... Closed
relates to MODUSERBL-25 Remove 'raml-local' from master branch Closed
Sprint:

 Description   

Tidy the "raml" repository (i.e. the shared raml-util) and each repository using it to ensure consistency.

(This issue started as "Split shared raml into separate components" and was later repurposed.)



 Comments   
Comment by Jakub Skoczen [ 07/Feb/18 ]

we have decided not to do this but instead David Crossley will clean up the raml repo and other repos to make sure we don't have any duplicates and it's clear where the schemas are maintained.

Comment by David Crossley [ 20/Feb/18 ]

Some raml-util are out-of-date. See listing attached compare-raml-util-2018022023.txt

Many may not need the most recent, but it would be better to be as recent as possible. Then also easier to update raml-util with more confidence.

Some recent updates were:
2018-01-16 : schemas/mod-users/userdata.json : Update userdata with metadata object. Require addressType field for addresstypes
2018-01-13 : schemas/resultInfo.schema : Add further diagnostics MODCXMUX-14 Closed
2017-12-08 : raml/schemas/metadata.schema : Fix the UUID pattern FOLIO-972 Closed

Comment by David Crossley [ 20/Feb/18 ]

Old duplicate copies of raml-util in mod-login mod-users mod-users-bl

mod-users-bl/raml would be better called "raml-util" like the rest.

Comment by David Crossley [ 20/Feb/18 ]

Okapi has a raml-util, which is not used but is mentioned in doc/guide.md in section "System Interfaces".

It is out-of-date. Either update, or remove and link the docs to the "raml" repository instead.

Comment by David Crossley [ 20/Feb/18 ]

Should shared "raml" repository have a NEWS.md file?

Should it have actual releases?

Comment by Jakub Skoczen [ 28/Feb/18 ]

This still seems to be an open issue, with two major points:

a) the various repos have diverged in terms of raml-util version used, we think it would be beneficial to tag ("release") the raml repo e.g as 1.1 and align the dependencies across different modules

b) it seems that the git-submodule approach to publishing and distributing interface definitions is suboptimal and we would benefit from a more robust tool like e.g Maven (or similar)

Let's discuss this on the core meeting next week (with initial discussion here).

Comment by Marc Johnson [ 28/Feb/18 ]

David Crossley From the looks of those changes, I think they'll have a minimal impact on compatibility.

If these are the only outstanding changes between the versions modules are on and the current revision, we could likely tag that and update them all to it.

bq .2018-01-16 : schemas/mod-users/userdata.json : Update userdata with metadata object. Require addressType field for addresstypes

This is specific to the users modules, so others are unaffected

2018-01-13 : schemas/resultInfo.schema : Add further diagnostics MODCXMUX-14 Closed

Those are all additional properties and server owned, so shouldn't affect compatibility until they are used

2017-12-08 : raml/schemas/metadata.schema : Fix the UUID pattern FOLIO-972 Closed

This is an expansion of the valid range (a weakening in effect) and so shouldn't effect compatibility

Comment by David Crossley [ 01/Mar/18 ]

Thanks, very helpful.

As per the attached list about half of the repos have raml-util older than that, so will need more investigation. The user-related and codex-related ones are recent, so easier.

Comment by David Crossley [ 06/Mar/18 ]

I reviewed the "raml" repository and each of the other raml-using repositories. Fixed some inconsistencies.

Also re-generated the attached listing of each project's date and version of its raml-util git submodule.

Comment by Adam Dickmeiss [ 20/Apr/18 ]

Last label was sprint33. Resolved or forgotten?

Comment by David Crossley [ 21/Apr/18 ]

Essentially done. (Many open issues were not rolled over to other sprints.)
I will review my notes and tidy up.

In the meantime i have been attending to semi-related issues.

Today updated the attached list of which versions of raml-util are currently in use. (Should be a separate issue.)

Comment by David Crossley [ 23/Apr/18 ]

This issue commenced with the title "Split shared raml into separate components". As per comment #1 we decided to not do that at this stage, but instead to ensure consistency. So modified the title to match.

Comment by David Crossley [ 23/Apr/18 ]

The inconsistencies are fixed. However ongoing monitoring is needed. A script to run raml-cop has been added to each repository (at ./scripts/lint-raml-cop.sh). Note that there are some potential inconsistencies that it does not detect ( FOLIO-1220 Closed ).

Comment by David Crossley [ 07/Sep/18 ]

Closed as done.

The raml-util is also better with the "raml1.0" branch RMB-198 Closed .

The lint-raml CI job FOLIO-1027 Closed also helps to verify.

Generated at Thu Feb 08 23:10:23 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.