search

cellannotation / cell-annotation-schema

General, open-standard schema for cell annotations
9 stars 1 forks source link

Make review easier #48

Closed dosumis closed 5 months ago

dosumis commented 8 months ago

Currently the schema is hard to review:

  1. Merge only happens in nightly releases and release artefacts are JSON blobs that default to download (rather than rendering) on GITHUB. As a result, judging and viewing integrated artefacts is hard, especially during editing/PRs.
  2. Users who are unfamiliar with JSON schema are also likely to find it hard to review.

Potential solutions:

  1. Render schema as a set of linked tables.
  2. Generation of markdown documentation from schema - various generic tools exist for this. Or we could use the system developed for DOSDP (see https://github.com/INCATools/dead_simple_owl_design_patterns/blob/master/docs/dosdp_schema.md for resulting doc - note CAS is much simpler)
  3. Generate reports following approaches in outline 1 or 2 or both on GA during tests run on PR.
  4. Autogenerate and commit these artefacts on merge to master (via GA)
    • with 4 in place - remember to UPDATE README to remove warning that content of derived files may be out of date.
dosumis commented 8 months ago

@hkir-dev - comments, questions please.

hkir-dev commented 8 months ago

Nightly release action can be manually triggered any time to generate release products. But, you are right, this is not very convenient as well. So, we can add a gogodiff like pull request comment trigger as well. This can generate release artefacts and attach as a comment. In this scenario we will still need to download json and browse locally. However, Github json rendering is not good any way (not able to expand/collapse objects etc.) so this option can be an acceptable solution. I afraid rendering as table would be extra confusing. If json has structural problems (still valid but has nesting problems etc.), it would be hard to debug from the tables generated in a distorted way. PR comment trigger may initiate documentation generation and commit to the working branch as well. But I think primary source for viewing and judging will be merged json schemas. This may be considered as a separate improvement task.

dosumis commented 7 months ago

Decision: Test Markdown doc solution developed for DOSDP schema & review.

hkir-dev commented 5 months ago

#rollschema pull request comment trigger added. This generates and comments both merged schemas and auto-generated comments.

See example: https://github.com/cellannotation/cell-annotation-schema/pull/78#issuecomment-1885091077