Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clean-up README #156

Merged
merged 2 commits into from
Dec 7, 2022
Merged

Clean-up README #156

merged 2 commits into from
Dec 7, 2022

Conversation

m-mohr
Copy link
Collaborator

@m-mohr m-mohr commented Dec 7, 2022

Some proposals for a cleaner README:

  • Directly link to examples and JSON Schema directly so that they are easy to find (the schema wasn't linked to at all from the spec, the spec itself wasn't linked to at all from the repo README)
  • Update version numbers to one consistent value instead of 0.4.0 and 0.5.0-dev in different places
  • Markdown tweaks, e.g. code fences
  • Remove "Optional" as it is in STAC to make it easier to see the difference directly. Only required fields are declared, all other are implicitly optional.
  • Don't hide links somewhere in the text

format-specs/geoparquet.md Outdated Show resolved Hide resolved
Co-authored-by: Tim Schaub <tschaub@users.noreply.github.com>
@tschaub tschaub merged commit 1ef95d7 into opengeospatial:main Dec 7, 2022
@tschaub
Copy link
Collaborator

tschaub commented Dec 7, 2022

Thanks, @m-mohr

@@ -52,21 +56,21 @@ but have a default geometry used for geospatial operations.

#### version

Version of the GeoParquet spec used, currently 0.4.0
Version of the GeoParquet spec used, currently 0.5.0-dev
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something I am wondering about this version number. While it is consistent to use this version here (as that is also used elsewhere, in the schema.json, etc), in practice we also don't really want that anyone would actually create files with this version?
Do we expect readers to understand that version? (or error for it?)

I am wondering that for readers of the spec, it might be more useful to say here "one of the released versions" instead of actually "currently 0.5.0-dev" ?

Copy link
Collaborator

@tschaub tschaub Dec 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jorisvandenbossche - I agree we need to do more cleanup on this. I think it would be enough for the description of the version metadata to say "The version identifier for the GeoParquet specification." Or we could include language about the "release" version as well. I don't think we need to repeat the actual version in this description. In addition, I think the whole "Additional file metadata information" section could be deleted, with the detail instead going in the description column in the table above.

Let's keep iterating on improvements.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, just removing the version number altogether in this location sounds good

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since #159 is about limiting the number of places the version identifier is repeated, I've made this change there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants