-
Notifications
You must be signed in to change notification settings - Fork 23
[WIP] API docs contrib guide #1592
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.
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
Conversation
# Find the workflow for your API docs | ||
|
||
:::{warning} | ||
This is WIP and apart from the quick reference is just a quick-and-dirty copy/paste from the Confluence doc |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is WIP and apart from the quick reference is just a quick-and-dirty copy/paste from the Confluence doc
IMO this isn't a good candidate for externalizing. Or if we do need a page like this, I'd suggest:
- removing any mention of things related to private repos, or "elastic employees only"
- removing the "Publishing process", "Automated?", and "Status" columns in the table since they're not pertinent to external contributors
- referring to the appropriate readmes for all the individual process details, so we are less likely to fall out of sync. For example:
- Elasticsearch: https://github.com/elastic/elasticsearch-specification?tab=readme-ov-file#how-to-generate-the-openapi-representation
- Kibana: https://github.com/elastic/kibana/blob/main/oas_docs/README.md (we can likely make this content better, but should be source of truth IMO)
- Observability intake service: https://github.com/elastic/apm-managed-service/blob/main/docs/spec/openapi/README.md
- Logstash doesn't have a readme but would be simple enough to create one here: https://github.com/elastic/logstash/tree/main/docs/static/spec/openapi
- summarizing the workflow at a high level, since it's essentially the same for all of them: check out the appropriate repo and branch, generate the OpenAPI output (per linked readmes), preview the output and verify that it satisfies the checklist, then open a PR to submit any changes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO this isn't a good candidate for externalizing.
Yeah this was just a conversation starter for "How do we co-locate a handy overview of the different processes/workflows with the contribution guidance and provide links" which we definitely need
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Or if we do need a page like this, I'd suggest:
I do think we need a page like this, but absolutely in accordance with 3-4
removing the "Publishing process", "Automated?", and "Status" columns in the table since they're not pertinent to external contributors
This isn't just for external contributors though, so we have to allow a little slack for co-locating important info, but yeah shouldn't be talking about super private stuff. But otherwise we have a public doc and a Confluence doc and nobody finds Confluence docs is something I hear all the time. It's also potentially helpful info for any external contributor to know at a glance that they can't contribute to Cloud API docs, for example. Anyways, probably a good debate topic.
removing any mention of things related to private repos, or "elastic employees only"
I don't mind that we mention a couple of private repos in a much more condensed and high-level version of this page, same reasoning as #1592 (comment)
If you find a bug in the contribution guide itself, please open a PR. | ||
For small edits that only touch a single page, click the **Edit this page** button. This will take you to the source file in GitHub, where you can make your changes and submit a PR. | ||
|
||
## Get help |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Get help
IMO this section should be removed since it's not the type of stuff I'd expect us to externalize.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Personally I'm OK with co-locating this information because I think realistically Elasticians will be the main consumers of this guidance, and it's helpful to have it all together, but it's a loosely-held position
Closing in favor of elastic/docs-content#2229 |
No description provided.