TASK: Make the SOS data easier to munch on

[indrora]

Currently, each service's SOS data is in one giant file. This means that there's a good risk of merge conflicts and there's even more chances for things to go wrong.

The SOS metadata should be split up into a few smaller chunks.

Suggestion:

1. Move the data out of .doc_gen
2. Make each service/language folder have the metadata for that service/language
3. Make it possible to auto-extract the snippets and "fill in the gaps"

so for SQS in Javav2, you'd have javav2/sqs/snippets.yml, for SNS in dotnet v3 it'd be dotnetv3/sns/snippets.yml

[Laren-AWS]

I don't think we should do this.

• I haven't found the metadata files to be too large or unwieldy. The current largest is IAM, which has ~38 examples and is 1447 lines and ~50K. It'll likely get somewhat larger (maybe 75K?) as we fill in the remaining 4 SDKs, but even then it's not hard to find examples by service_Action in the list.
• I have not had many merge conflicts while adding metadata, but those I've had have been easy to resolve. This is one of the things Git is made for, so I think this is a plus: we're using a well-built tool to catch and identify issues before they become problems.
• If we divide examples across multiple files, we risk human error and worse conflicts. For example, if we have sns_CreateTopic in both go_metadata.yaml and in dotnet_metadata.yaml, which title/synopsis/etc. is the primary one? Also, what if one of the writers mistypes the name? Then we'd have two examples, such as sns_CreateTopic and sns_create_topic, that are actually the same example. We'd have to write a tool to detect and resolve these kinds of conflicts and mistakes.
• Splitting into multiple files makes it harder to find an existing example. I'd have to search across all of the metadata files in the repo to determine if there's an sns_CreateTopic example hiding somewhere.
• I don't know exactly what you mean by auto-extract, but I'm guessing you mean a tool that scans code files and determines which snippets match up with which examples in the metadata and then injects metadata for them? My gut feel is that this would be more work than it's worth and is only really useful during our SOS cleanup phase so not worth the investment.

[brmur]

@indrora I agree with Laren that we'd be complicating the process (& adding work) to split the metadata. However, I'll poll the team to establish whether merge conflicts merit the changes you're proposing.

[indrora]

My observations so far:

• I've had three major merge conflicts with the SOS data. It wasn't hard to figure out how to fix it, but the times I did fix it, I didn't feel confident.
• 1400 lines of raw YAML is horrendous to deal with.

as for "where do the titles come from", here's a draft of my suggestion:

metadata/ebs.yml would look like

ebs_StartSnapshot:
  title: Create a &EBS; snapshot using an &AWS; SDK
  title_abbrev: Create a snapshot
  synopsis: create an &EBS; snapshot.
  category: []
  services:
    ebs: {StartSnapshot}

rust/ebs/snippets.yml would look like

ebs_StartSnapshot:
  - sdk_version: 1
     github: rust/ebs
     tag: ebs.rust.create-snapshot-start

meanwhile, this might be more complicated in another language:

ruby/ebs/snippets.yml

ebs_StartSnapshot:
  - sdk_version: 1
     github: ruby/ebs
     body:
       - tag: ebs.ruby.create-snapshot-start
         before: Start the &EBS; volume snapshot
       - tag: ebs.ruby.create-snapshot-wait
         before: In order to make sure further &EBS; operations work right, you must wait for the state to change to READY
         after: The &EBS; snapshot is now in progress and you can continue working with the volume.

as for automatically associating these snippets, the Rust example I gave could easily be simply declared inline:

//snippet-start[ebs.rust.create-snapshot-start]
//snippet-group[ebs_CreateSnapshot]
...
//snippet-end[ebs.rust.create-snapshot-start]

[Laren-AWS]

I need more data on "major" and "horrendous".

• In my experience, I've had minor merge conflicts that were easily resolved, and the process is to push conflict resolution back to the author because they are the expert on their changes.
• I have not found the yaml file hard to deal with. What tool are you using to edit the yaml? What defines "horrendous"?

Your proposed format change:

• There's some merit to your suggestion of dividing the metadata into primary and secondary components. Distributing the metadata in this way introduces some greater flexibility.
• We would need to carefully consider the ramifications of your solution. It would require more extensive error checking to verify some things about secondary metadata, for example:
  • Primary example with no secondaries.
  • Secondary example with no primary.
  • Typos or mismatched names between primary and secondary.
  • Duplicate secondaries (because they're split across multiple files).
• Need to clarify what gains there are (if any) to introducing greater complexity to the tool and potential fragility to the data.

Extra tag in code:

• I don't see the advantage to introducing an additional tag in the source code. Adding clutter to the source is a negative for customer experience, and this linkage is already in the metadata.