Document guaranteed/non-guaranteed hub structure and best practices for downstream products

[dylanhmorris]

• Guide users building downstream products to hubverse tooling rather than direct use of repo file structure
  • Consider encouraging people to use the S3 bucket rather than the hub github?
• Explicitly warn that repo file structure, auxiliary data files, etc are not guaranteed by default.
• Encourage users to make issues if there are things not available via hubverse tooling that they need and we can provide with a stronger guarantee. auxiliary-data/stable?
  • Perhaps the hubverse itself should have a standard and API for this? We could open an issue.

[emprzy]

All looks very reasonable. I am curious by which channels will there be notification of future changes? Just a PR on this hub repo?

Just want to make sure I am staying alert by checking in the right places.

[dylanhmorris]

My thought is when changing anything more "guaranteed", we'd go through a formal deprecation cycle. We'd flag planned changes: (1) in the hub docs and (2) on our email list.

The docs will also highlight that non-guaranteed features of the Hub may change without warning / a formal deprecation cycle.

[sbidari]

Following seem like concrete steps (I can create issues/assign if you agree @dylanhmorris @O957):

• Maintain a list of external downstream hub products where users can register their use of files in this repo and can get notified of planned changes. This will obviously be optional but provide benefit of being notified of changes.
• Add a section on accessing hub data from the cloud (there is a version of this on the RSVHub but on for COVIDHub) and users can decide best option for their use case.
• Add a disclaimer/warning about non-guarantee of existing file structure (I am not even sure we need this possibly nice to have)

[O957]

Re: #1395 (comment)

Need to think these over some more but initial impression is that these all seem like sensible actions to take.

[emprzy]

@dylanhmorris , how can we get on the email list?

[dylanhmorris]

Please email covidhub@cdc.gov with a list of addresses you'd like added.

[dylanhmorris]

Following seem like concrete steps (I can create issues/assign if you agree @dylanhmorris @O957):

• Maintain a list of external downstream hub products where users can register their use of files in this repo and can get notified of planned changes. This will obviously be optional but provide benefit of being notified of changes.
• Add a section on accessing hub data from the cloud (there is a version of this on the RSVHub but on for COVIDHub) and users can decide best option for their use case.
• Add a disclaimer/warning about non-guarantee of existing file structure (I am not even sure we need this possibly nice to have)

I like all of these ideas (and do think the third one is definitely worth doing). I would just add that I'd lump them all into a "guidelines for using hub data in downstream products" or similar document/section.