[FOLIO-1447] FOLIO policy for RAML and JSON descriptions Created: 29/Aug/18 Updated: 07/Feb/19 |
|
| Status: | Blocked |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | New Feature | Priority: | P3 |
| Reporter: | Tod Olson | Assignee: | David Crossley |
| Resolution: | Unresolved | Votes: | 0 |
| Labels: | ci, core, potential-q1, sprint, sprint47, sprint48, sprint49, sprint50, sprint51, sprint52, sprint53, sprint54 | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Issue links: |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sprint: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Development Team: | Core: Platform | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Description |
|
Set policies to encourage supplying descriptions in RAML and JSON schema. These descriptions are useful documentation and the project needs some policies to encourage supplying the descriptions. They are particularly useful for people getting familiar with a module, for example in planning data migration. Related to
|
| Comments |
| Comment by Jakub Skoczen [ 18/Sep/18 ] |
|
David Crossley can we add a rule in the raml linter to warn about missing description fields in the JSON schema? |
| Comment by David Crossley [ 19/Sep/18 ] |
|
Got something basic happening. The lint-raml CI job operates on branch builds and PRs. It now also finds all schemas, ensures top-level "description" and assesses "properties" to ensure a description for each. Currently only as warnings. So it will only be seen on the GitHub if there are also raml-cop errors. So see the report of a recent build by following through to the Jenkins output and see "Artifacts" at the top-right. It excludes "metadata, resultInfo, totalRecords" (can add others). It only investigates top-level "properties", not any nested. Excluded all of "acq-models" for now. |
| Comment by David Crossley [ 28/Sep/18 ] |
|
The lint-raml CI job now logs errors for the missing JSON schema description fields. It does not cause the Jenkins build stage to fail. It will just show the errors. |
| Comment by David Crossley [ 01/Oct/18 ] |
|
Now it assesses the nested properties. |
| Comment by David Crossley [ 01/Oct/18 ] |
|
There is a basic document at dev.folio.org/guides/describe-schema/ |
| Comment by David Crossley [ 02/Nov/18 ] |
|
The document at dev.folio.org/guides/describe-schema/ has been improved, and also linked back to these issues (this
Note that this lint-raml CI job only assesses missing "description" fields. |
| Comment by Marc Johnson [ 08/Nov/18 ] |
|
David Crossley I would like to be able to check the general validity of the RAML and schema before checking for missing descriptions. Is it already possible to skip those checks? Or if not, would it be possibly to add a parameter to disable the checks for for missing description properties in the lint-raml.py script. |
| Comment by David Crossley [ 09/Nov/18 ] |
|
Sure Marc. That is done now, so use the arg "--validate-only" (i.e. -v). |
| Comment by Marc Johnson [ 09/Nov/18 ] |
|
David Crossley Thanks, that works great |
| Comment by Jakub Skoczen [ 11/Dec/18 ] |
|
The missing description issues should be addressed in Q1. |