chore: regenerate 8.7 C8 REST API docs from upstream stable/8.7 branch
#4979
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
👋 🤖 🤔 Hello, @pepopowitz! Did you make your changes in all the right places? These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.
You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines. |
pepopowitz
commented
Feb 11, 2025
| @@ -601,7 +601,7 @@ paths: | |||
| To change the time, the clock must be pinned again with a new timestamp. | |||
|
|
|||
| :::note | |||
| This endpoint is an [alpha feature](/reference/alpha-features.md) and may be subject to change | |||
There was a problem hiding this comment.
I will open a PR to remove these links upstream. The source should not contain any link at all (the generation process should inject them), but the stable/8.7 spec includes it in two places.
There was a problem hiding this comment.
Probably something we took over from stable/8.6 to stable/8.7 in the OpenAPI spec, I assume. If so, let's fix it in both places.
Pro tip: fix it on one branch with a PR (e.g. stable/8.6), add a backport stable/8.7 label to that PR. The fix will get auto-backported to whatever the other branch is.
| @@ -121,7 +121,7 @@ curl --header "Authorization: Bearer ${TOKEN}" \ | |||
| ${ZEEBE_REST_ADDRESS}/v2/topology | |||
| ``` | |||
|
|
|||
| A successful response includes [information about the cluster](/apis-tools/camunda-api-rest/specifications/get-topology.api.mdx). For example: | |||
| A successful response includes [information about the cluster](/apis-tools/camunda-api-rest/specifications/get-cluster-topology.api.mdx). For example: | |||
There was a problem hiding this comment.
The PR includes a small handful of changes like this -- 8.7 docs that are referencing endpoints that are named differently in the stable/8.7 spec.
There was a problem hiding this comment.
Is the basis for our 8.7 docs the 8.6 docs or the 8.8 docs? I assume we branched off the former "next" into "next 8.7"? That would explain something like this.
There might be other things that "suffer" from this then, I could imagine. The former "next" docs contained a lot of stuff already that are not really meant for the "new" 8.7 now.
There was a problem hiding this comment.
Ugh, annoying detail of the generation process -- an updated sidebar file gets generated, which is great, but it lives here inside the content. Because this is a cut/numbered version, and docusaurus only supports top-level json sidebars files for cut versions, we can't import this into this version's sidebars. Instead, I had to manually take this output and slap it into the top-level json sidebar file for this version. This makes the self-serve "generate docs for API version x" idea a little less self-serve, unless it's not a large amount of work to automatically replace a portion of the top-level JSON.
versioned_docs/version-8.7/apis-tools/migration-manuals/migrate-to-camunda-api.md
Show resolved
Hide resolved
pepopowitz
added
component:docs
|
@pepopowitz I don't know what vale is mad about, but it looks like the link issues are still there. Want me to look at these? Was hoping to deploy a preview site to review. |
the issue is that there are 3 api endpoints that either moved or didn't exist in 8.7. They weren't found earlier in the build because they're nested inside a table, where markdown links don't work; they're only found later when checking link URLs. I pushed a change that fixes one of them, but two of them I don't think have an 8.7 counterpart. I actually am going to push up another change to mark them as having no counterpart. |
pepopowitz
commented
Feb 11, 2025
versioned_docs/version-8.7/apis-tools/migration-manuals/migrate-to-camunda-user-tasks.md
Show resolved
Hide resolved
versioned_docs/version-8.7/apis-tools/migration-manuals/migrate-to-camunda-user-tasks.md
Show resolved
Hide resolved
georgios-goulos
approved these changes
Feb 12, 2025
tmetzke
reviewed
Feb 12, 2025
| @@ -329,6 +329,6 @@ The following conventions apply to all attributes: | |||
|
|
|||
| <!--- TODO: insert link to C8 REST API guidelines ---> | |||
There was a problem hiding this comment.
❓ Does it really make sense to have this guide in 8.7 already? I believe this is only suited for 8.8, to be honest. This is one of things, as mentioned earlier, that we added to "next" already and now does not really make sense for "8.7 next" if you ask me. In the end, 8.7 now only is 8.6 with a couple of RPA/IDP/AI/Document handling on top. The docs should reflect this the same way, I think. Not saying that is simple to do, but we'll encounter more of these "not yet for 8.7" parts, I feat.
There was a problem hiding this comment.
I don't have a strong opinion here, but I'd prefer to handle this in a follow-up.
tmetzke
reviewed
Feb 12, 2025
| @@ -239,7 +239,7 @@ The following table outlines the respective endpoints. Click the endpoints to fo | |||
| </a> | |||
| </td> | |||
| <td> | |||
| <a href="../../camunda-api-rest/specifications/find-user-tasks"> | |||
| <a href="../../camunda-api-rest/specifications/query-user-tasks-alpha"> | |||
There was a problem hiding this comment.
❓ Same as for the guide above, I believe this should stay on the 8.6 level, as we haven't added anything on top with 8.7, as far as I can tell.
There was a problem hiding this comment.
I don't have a strong opinion here, but I'd prefer to handle this in a follow-up.
tmetzke
reviewed
Feb 12, 2025
| @@ -200,7 +200,7 @@ This [alpha release](/reference/release-policy.md) contains a known issue where | |||
|
|
|||
| You can now use a single Query API in the Camunda 8 REST API to find process and decision data instead of using multiple component APIs. | |||
There was a problem hiding this comment.
💭 This page is going to be confusing for people, I could imagine. The alphas until 8.7.0-alpha3 contributed to what now is 8.8, actually. The stuff mentioned there is not reflected (entirely) in 8.7.0 anymore. That is a tricky page now. One thought here: maybe we move the alphas until alpha3 to 8.8 and explain there that those changes contributed to 8.8 and not 8.7. Here in 8.7 we start listing from alpha4. In the end, this is what we ACTUALLY did so maybe this should also be reflected in the docs as well.
There was a problem hiding this comment.
Let's handle this outside the scope of this PR. @conceptualshark has been shifting things around to reflect what is and isn't delivered in 8.7 vs. 8.8, including things delivered and shifted in alphas.
tmetzke
approved these changes
Feb 12, 2025
|
🧹 Preview environment for this PR has been torn down. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Follow-up to #4956.
This PR regenerates the version 8.7 C8 REST API docs, based on the upstream camunda/camunda repo's
stable/8.7branch.When should this change go live?
bugorsupportlabel)available & undocumentedlabel)holdlabel)low priolabel)PR Checklist
/docsdirectory (aka/next/)./versioned_docsdirectory. Kind of.....@camunda/tech-writersunless working with an embedded writer.