Initial "wireframe" for model contracts

[jtcohen6]

resolves #2839
resolves #2594 (includes #2601)

waiting on v1.5 initialization (#2842)

What are you changing in this pull request and why?

Opening an early draft PR for discussion!

My goal right now is just to stand up some initial "wireframes" with suggestive/placeholder content. A lot of the language will need refining, and the content will need deduplicating/reorganizing. Our goal is to push up iterative changes early & often, so we can gather regular feedback. I feel good about these pages being:

• Visible in the sidebar only if you have v1.5 selected
• Clearly called out as "Beta functionality" and "Under construction 🚧"

Specific changes:

• Create new section under "Docs > Collaborate with others": "Publishing models."
  • Most of the other pages under "Collaborate" are about environments, version control, documentation — not generally dbt-core project source code. But our goal in the multi-project initiative is all about "scaling collaboration"! Does this feel out of place?
  • What do we think of "Publishing models" as naming/framing? Elsewhere I've been referring to this slice of the initiative with the tagline "Models as APIs."
• Create "narrative" pages for "Model contracts." Also create initial pages for "Model access" (Narrative: Model groups & access #2840) and "Model versions" (Narrative: Model versions #2841), but these are really just skeleton pages for now, missing a lot of important narrative.
• Create reference pages for contract & constraints. These pages will need to be reworked as we rework the functionality & syntax—a good thing! I tried to call out explicitly places where I expect us to come back and edit/update.

Checklist

• Add versioning components, as described in Versioning Docs
• Add a note to the prerelease version Migration Guide
• Review the Content style guide and About versioning so my content adheres to these guidelines.
• Add a checklist item for anything that needs to happen before this PR is merged, such as "needs technical review" or "change base branch."

Adding new pages (delete if not applicable):

• Add page to website/sidebars.js
• Provide a unique filename for the new page

[netlify]

✅ Deploy Preview for docs-getdbt-com ready!

Name	Link
🔨 Latest commit	4eee716
🔍 Latest deploy log	https://app.netlify.com/sites/docs-getdbt-com/deploys/63fcbba117c2f500083d8ad7
😎 Deploy Preview	https://deploy-preview-2890--docs-getdbt-com.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[jtcohen6]

No functional change here, I just reordered the list so it's in a consistent (descending) order by firstVersion. I figure, in the future, we could remove items from this list as we deprecate older versions.

[matthewshaver]

Thank you!

[matthewshaver]

I wanted to note two particular editorial changes in case others have strong feelings about them:
"guarantees" and "pre-flight" were replaced with "parameters" and "prerequisites," respectively. Part of my duties is to prepare our documents for translation sometime in the future. These words (in their context here) may result in confusion or difficulties for readers who don't speak English as a primary language. As this is a new feature, and one that seems very important, I wanted to ensure that these documents are as clear as possible for all of our readers.

[dbeatty10]

Smart to prepare for translation, @matthewshaver 🧠

It is feeling awkward to me when reading "prerequisite check" in context currently. Is there an option to re-phrase this in a way that simultaneously prepares for translation and reads more smoothly?

[jtcohen6]

@matthewshaver @dbeatty10 Love that we're having this conversation! I will say that "parameters" and "prerequisites" don't feel quite right. Let's find the right words, both to capture the meaning and to enable eventual translation into other languages!

Parameters feels much too vague of a term. A "parameter" could be any model attribute/property/configuration, and it doesn't carry the same force of consistent truth. What I'm after here is, a set of things that are guaranteed to be true about the structure of this model and the dataset it produces. They're guaranteed because, if they're found to be untrue, the model doesn't build! "The thing I am telling you will be true, because it cannot be otherwise. Es muss sein. If it must be otherwise, then I must first change the thing that I am telling you." Other words here: "contract" (we're already using this one!), "commitment" around the "shape" or "structure" of the data...?

Prerequisite to me implies, a thing the user must do in order to be able to use this feature. There's some truth to that—the user must define the name and data_type for every column in yaml, in advance of running it — but the real feature here is a thing that dbt is doing. Before the model builds, dbt will ensure that the SQL and the yaml match up. This is the pre-flight check. Other words I could think of here: "verification," "safeguard," "precaution."

[matthewshaver]

I went with "verification" rather than prerequisites.

Regarding the contracts, I slipped the word "guarantee" back in and clarified it with "attestations," which might be a more comfortable and broadly understood word in the software world. Let me know if that still doesn't hit right and maybe we can revert to the original form in the interest of shipping.

[dbeatty10]

@matthewshaver

We've been using the following to phrases pretty frequently while iterating on contracts:

• "pre-flight" check
• "guarantees"

In the interest of shipping, how would you feel about adding those back in for now with the promise that we'll spend more time re-considering this verbiage before the final 1.5 release?

I don't really have a horse in the race for the exact phrasing here. But I do think that we'd get a lot of value out of getting and initial version of these docs published.

[matthewshaver]

No problem. Plenty of time in the future to have these convos. It's reverted and my review is complete. Ready for merge as soon as you're ready to take it out of draft @jtcohen6 !

[jtcohen6]

Thanks for the work on this @matthewshaver @dbeatty10!

Plenty of time to have more convos & more rereads/reviews. I'm marking this as "Ready" in the spirit of getting docs live early & often, to accompany our early & often beta prereleases :)