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.

Sign up for GitHub

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

Jump to bottom

Add doc on API stability #4326

Closed
wants to merge 1 commit into from
Closed

Add doc on API stability #4326

wants to merge 1 commit into from

Conversation

knz
Copy link
Contributor

@knz knz commented Feb 6, 2019

Here is a doc which does two things:

  • it clarifies what external users can depend on
  • it clarifies "experimental" vs "beta" vs "stable"

cc @BramGruneir @mjibson @bobvawter @jordanlewis for checking this is aligned with our actual practices so far and aspirations for the future.

cc @rmloveland for further editing and integration in the docs.

cc @bdarnell to sign off on the stability commitments.

cc @rolandcrosby @awoods187 to acknowledge the compatibility and visibility commitments.

@knz knz added the in progress label Feb 6, 2019
@cockroach-teamcity
Copy link
Member

This change is Reviewable

@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/c38d288714cfb25abb08e441e4dafba453f63026/

@knz knz force-pushed the 20190206-api-stability branch from c38d288 to 7f6283e Compare February 6, 2019 11:27
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/7f6283e7fa7dc9432465a50f185716a34ae66ce7/

@knz knz force-pushed the 20190206-api-stability branch from 7f6283e to ea02735 Compare February 6, 2019 11:33
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ea02735ab73abbcd57deb2d1527d85e03f2610df/

@knz knz force-pushed the 20190206-api-stability branch from ea02735 to 48e460c Compare February 6, 2019 11:45
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/48e460c65e71447331d99b68dbe7ba75b022c29d/

@knz knz force-pushed the 20190206-api-stability branch from 48e460c to b6e7aec Compare February 6, 2019 11:58
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/b6e7aec2f60ac74967c7aea7268373fe2c0e7970/

@knz knz force-pushed the 20190206-api-stability branch 3 times, most recently from 4b57dce to b49e6fe Compare February 6, 2019 12:16
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/b49e6fe18d26739aa94f9a473d1aff605a7e5c5d/

@knz knz force-pushed the 20190206-api-stability branch 2 times, most recently from 25fa9f2 to 8c2d7df Compare February 6, 2019 12:26
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/25fa9f21ad992d2d65e4e3161e7a97484403c342/

@knz knz force-pushed the 20190206-api-stability branch from 8c2d7df to c18f5ab Compare February 6, 2019 12:28
@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/8c2d7dfef7e965f4ec46e9a6b005d5cb9e43ca48/

@cockroach-teamcity
Copy link
Member

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/c18f5ab2c95d9b704871cfb9f834378f17f2fd32/

@knz knz force-pushed the 20190206-api-stability branch from c18f5ab to 1ba118b Compare February 6, 2019 12:45
@cockroach-teamcity
Copy link
Member

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/cd5fd8f227d79c2220f92138946cd92e7e55c565/

Edited pages:

ericharmeling
ericharmeling reviewed Sep 27, 2019
View reviewed changes
Copy link
Contributor

@ericharmeling ericharmeling left a comment

Choose a reason for hiding this comment

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

@knz ... Breaking this up makes it a lot easier to digest, not to mention a much better navigation experience.

I have a lot of suggestions and changes (information architecture/wording/etc.), so I've made my own branch against this PR, in which I've started going through the files one-at-a-time. Given that we have other release-specific documentation that takes priority over this, I don't know how soon I will be able to go through all of it.

So, my suggestion at this point would be that we open a new PR with the very high-level stuff from this PR (i.e. interface-types.md and overview-of-apis-and-interfaces.md and compatibility-and-programming-guarantees.md), and then start adding the docs specific to the interfaces/guarantees piece-by-piece in separate PR's (i.e. sql-functional-behavior-guarantees.md, introspection-interfaces.md, et al each get their own PR). I can open that new PR that just touches the high-level stuff, and get you and @jseldess to review, and then I can move on to the "interface-specific" PR's. I'm thinking I'd add introspection-interfaces.md to #5454, making that the first "separate PR" that includes stability doc specific to one of the interfaces. I know it won't make much sense writing about "public/programmable", etc, without having designated those categories to each interface, but I think starting with the overview, then with a piece at a time is a good way to push this forward. Thoughts?

Reviewable status: :shipit: complete! 0 of 0 LGTMs obtained (waiting on @awoods187, @bdarnell, @danhhz, @ericharmeling, @jordanlewis, @knz, @mjibson, and @rmloveland)

@knz
Copy link
Contributor Author

knz commented Sep 27, 2019

o, my suggestion at this point would be that we open a new PR with the very high-level stuff from this PR (i.e. interface-types.md and overview-of-apis-and-interfaces.md and compatibility-and-programming-guarantees.md), and then start adding the docs specific to the interfaces/guarantees piece-by-piece in separate PR's

Works for me. The 3 first pages you listed here are the most important anyway. (I would recommend also including the experimental-feature-lifecycle.md in there because it comes up a lot too)

ericharmeling added a commit that referenced this pull request Oct 3, 2019
@ericharmeling
CRDB interface stability docs
f0f208b 
- Overview of CockroachDB Interfaces
- Interface Types
- Stability Guarantees
- The Lifecycle of Experimental, Beta, and Stable Features

This commit is a modified version of @knz's API stability doc (#4326)
@ericharmeling ericharmeling mentioned this pull request Oct 3, 2019
Closed
ericharmeling added a commit that referenced this pull request Oct 3, 2019
@ericharmeling
CRDB interface stability docs
10c9fc3 
- Overview of CockroachDB Interfaces
- Interface Types
- Stability Guarantees
- The Lifecycle of Experimental, Beta, and Stable Features

This commit is a modified version of @knz's API stability doc (#4326)
ericharmeling added a commit that referenced this pull request Oct 3, 2019
@ericharmeling
CRDB interface stability docs
cd528fc 
- Overview of CockroachDB Interfaces
- Interface Types
- Stability Guarantees
- The Lifecycle of Experimental, Beta, and Stable Features

This commit is a modified version of @knz's API stability doc (#4326)
ericharmeling added a commit that referenced this pull request Oct 8, 2019
@ericharmeling
CRDB interface stability docs
b8834a9 
- Overview of CockroachDB Interfaces
- Interface Types
- Stability Guarantees
- The Lifecycle of Experimental, Beta, and Stable Features

This commit is a modified version of @knz's API stability doc (#4326)
@rmloveland rmloveland mentioned this pull request Oct 24, 2019
Closed
ericharmeling added a commit that referenced this pull request Nov 4, 2019
@ericharmeling
CRDB interface stability docs
2186d62 
- Overview of CockroachDB Interfaces
- Interface Types
- Stability Guarantees
- The Lifecycle of Experimental, Beta, and Stable Features

This commit is a modified version of @knz's API stability doc (#4326)
@piyush-singh piyush-singh mentioned this pull request May 27, 2020
Closed
@knz knz force-pushed the 20190206-api-stability branch from cd5fd8f to d7a1e5f Compare July 8, 2020 16:03
@netlify
Copy link

netlify bot commented Jul 8, 2020 •
edited
Loading

‼️ Deploy request for cockroachdb-docs rejected.

Name Link
🔨 Latest commit d7a1e5f

@cockroach-teamcity
Copy link
Member

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/d7a1e5f67d02cc15d495dbcdb521679686c5e356/

Edited pages:

@knz knz force-pushed the 20190206-api-stability branch from d7a1e5f to 7a1bdec Compare August 5, 2020 13:56
@cockroach-teamcity
Copy link
Member

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/7a1bdec1b16e17e2e1dc65fa9bd59dbd4f7b3658/

Edited pages:

@jseldess
Copy link
Contributor

@taroface, given the publication of https://www.cockroachlabs.com/docs/stable/api-support-policy.html, should this PR be closed?

@taroface
Copy link
Contributor

taroface commented Aug 16, 2022 •
edited
Loading

@jseldess I think so, but since this is a big PR, I'd like to confirm with @knz that there isn't some work in here that we might wish to repurpose for a future update or enhancement. Thank you for calling this out!

@knz
Copy link
Contributor Author

knz commented Aug 17, 2022

let's call this a day -- if we want more fine grained mentions of APIs, the folk now owning the areas can spell out their rules themselves now.

@knz knz closed this Aug 17, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ericharmeling ericharmeling ericharmeling left review comments

@awoods187 awoods187 awoods187 left review comments

@rmloveland rmloveland rmloveland left review comments

@bdarnell bdarnell Awaiting requested review from bdarnell

@danhhz danhhz Awaiting requested review from danhhz

@jordanlewis jordanlewis Awaiting requested review from jordanlewis

@maddyblue maddyblue Awaiting requested review from maddyblue

Assignees

@jordanlewis jordanlewis

@bdarnell bdarnell

@rmloveland rmloveland

@awoods187 awoods187

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.