Bug 41116 - Use YAML front-matter for workbook metadata rather than JSON
Summary: Use YAML front-matter for workbook metadata rather than JSON
Status: RESOLVED FIXED
Alias: None
Product: Workbooks & Inspector
Classification: Xamarin
Component: Client: Cross Platform (Shared Code) ()
Version: 0.8.0
Hardware: PC Windows
: --- normal
Target Milestone: ---
Assignee: inspectordev-discuss
URL:
Depends on:
Blocks:
 
Reported: 2016-05-16 17:39 UTC by Daniel Cazzulino
Modified: 2016-05-26 21:33 UTC (History)
3 users (show)

Tags:
Is this bug a regression?: ---
Last known good build:


Attachments
A workbook that makes a compelling (I think ;)) case for using YAML (3.99 KB, application/x-xamarin-workbook)
2016-05-16 17:39 UTC, Daniel Cazzulino
Details
This workbook actually loads (fixed typo) (3.99 KB, text/plain)
2016-05-16 17:42 UTC, Daniel Cazzulino
Details
The one with the missing HttpClient dependency (3.99 KB, text/plain)
2016-05-16 17:46 UTC, Daniel Cazzulino
Details


Notice (2018-05-24): bugzilla.xamarin.com is now in read-only mode.

Please join us on Visual Studio Developer Community and in the Xamarin and Mono organizations on GitHub to continue tracking issues. Bugzilla will remain available for reference in read-only mode. We will continue to work on open Bugzilla bugs, copy them to the new locations as needed for follow-up, and add the new items under Related Links.

Our sincere thanks to everyone who has contributed on this bug tracker over the years. Thanks also for your understanding as we make these adjustments and improvements for the future.


Please create a new report on Developer Community with your current version information, steps to reproduce, and relevant error messages or log files if you are hitting an issue that looks similar to this resolved bug and you do not yet see a matching new report.

Related Links:
Status:
RESOLVED FIXED

Description Daniel Cazzulino 2016-05-16 17:39:15 UTC
Created attachment 16013 [details]
A workbook that makes a compelling (I think ;)) case for using YAML

Attached is a workbook that makes the case for using YAML for workbook metadata, 
including sample code and metadata, how it's read and how it can be trivially 
converted back to JSON to drive whatever internals we have currently that 
depend on the JSON metadata present in current workbooks. 

Maybe it should be pretty straightforward to even support both ;)

The first few paragraphs make the case as follows:

Workbooks are great because you can just upload them to GitHub and have people collaborate
even just using a brower: update, send pull requests, merge, comment on lines, etc.

Anyone who has used Jekyll (meaning anyone who has used GitHub Pages) is likely familiar
with Front-Matter, which basically is markup at the begining of the document which is
distinct from the rest because it uses a totally different markup:

    ---
    layout: post
    title: Blogging Like a Hacker
    ---

The front-matter isn't just more readable while editing the text file, it's also 
rendered nicely by GitHub itself, as can be seen here https://github.com/kzu/sandbox/blob/master/YamlFrontMatter.md 

That markdown document is the YAML-ized version of the attached workbook itself, so you can 
see how much better it is in GitHub ;)
Comment 1 Daniel Cazzulino 2016-05-16 17:42:45 UTC
Created attachment 16014 [details]
This workbook actually loads (fixed typo)
Comment 2 Daniel Cazzulino 2016-05-16 17:46:37 UTC
Created attachment 16015 [details]
The one with the missing HttpClient dependency
Comment 3 Miguel de Icaza [MSFT] 2016-05-17 03:03:47 UTC
For what it is worth, I like this idea, purely on the github grounds.

We would have to keep both file readers in place, as the last thing I want to do is break existing workbooks, even the handful that exist out there.

And start using the new file format for the new ones we produce.
Comment 4 Aaron Bockover [MSFT] 2016-05-17 14:12:37 UTC
I agree, also purely on the Github grounds. We would absolutely implement this with backwards compatibility in mind.
Comment 5 Daniel Cazzulino 2016-05-17 14:38:22 UTC
Maybe on read, we support both, and on write, we emit the YAML version (since going from one to the other is really straightforward from the code point of view). Supposedly, JSON is a valid subset of YAML.
Comment 6 Aaron Bockover [MSFT] 2016-05-26 13:17:11 UTC
Yes, we would migrate any JSON manifests to YAML. JSON serialization would be removed while deserialization would be kept for migration to YAML.
Comment 7 Aaron Bockover [MSFT] 2016-05-26 21:33:10 UTC
This is implemented in master and will be in the next release.