chore: project setup — Makefile, CI/CD, GitHub templates, copilot instructions#2
Merged
Conversation
…ot instructions - Rename project to arubacloud-api-portal - Add Makefile with install, start, build, clean, regen-api-docs, pre-pr targets - Add CONTRIBUTING.md with full development workflow guide - Rewrite README.md with badges, quick start, API coverage table - Add .github/workflows/deploy.yml for GitHub Pages deployment - Add .github/workflows/pr-validation.yml for PR build checks - Add .github/ISSUE_TEMPLATE (bug, feature, docs, openapi) - Add .github/PULL_REQUEST_TEMPLATE.md - Add .github/copilot-instructions.md for AI assistant context - Fix gen-api-docs/clean-api-docs scripts to pass 'all' argument - Fix gen-api-docs:version/clean-api-docs:version for compute v1.1 - Add webpack fallback plugin to suppress postman-code-generators path errors
Run clean-api-docs + gen-api-docs all to sync generated .api.mdx files with the installed theme version and fix @theme/ResponseSamples errors. Also runs gen-api-docs:version for compute v1.1. NOTE: compute v1.0 base endpoint files are currently not regenerated by gen-api-docs all when a versions key is present in the config. This requires further investigation.
The build was failing on all 194 API pages with: Error: useTabsContext() must be used within a Tabs component This is a version incompatibility between docusaurus-plugin-openapi-docs v4.7.1 and Docusaurus 3.10.1 (which ^3.7.0 resolved to in CI). The plugin's SchemaTabs/MimeTabs components conflict with how Docusaurus 3.10.x handles the Tabs React context during SSG. Pin all @docusaurus/* packages to exact version 3.7.0 and regenerate package-lock.json to lock CI to the compatible version.
Two separate bugs were blocking the build: 1. useTabsContext() SSG crash (all 194 pages): Introduced in docusaurus-plugin-openapi-docs 4.7.1. The SchemaTabs/ MimeTabs components call useTabsContext() unconditionally during SSG, but Docusaurus throws when useTabsContext() is called outside a Tabs context. Pinning the plugin to 4.1.0 avoids this regression. 2. webpack ProgressPlugin schema error: Pinning @docusaurus/core to 3.7.0 (exact) caused a webpack 5.106 schema validation error because Docusaurus 3.7.0 passes reporter:null to ProgressPlugin, which webpack 5.106 no longer accepts. This was fixed in later Docusaurus versions; we stay on 3.10.1 via ^3.7.0. Final combination: Docusaurus 3.10.1 + plugin 4.1.0 + theme 4.1.0. Regenerated all API docs with plugin 4.1.0.
- Add postinstall.js to patch docusaurus-theme-openapi-docs@4.1.0:
* Fix useTabs(props) -> useTabsContextValue(props) in 6 tab components
(SchemaTabs, MimeTabs, OperationTabs, DiscriminatorTabs, ApiTabs, CodeTabs)
* Wrap TabsComponent JSX in TabsProvider so TabItem context reads work
* Downgrade duplicate sidebar translation key error to warning (pre-existing
issue now surfaced by Docusaurus 3.10.x strict check)
- Fix gen-api-docs:version and clean-api-docs:version command syntax:
'compute 1.1' -> 'compute:1.1' (plugin expects <id:version> format)
- Regenerate docs/documents/compute/1.1/ with corrected plugin invocation;
create-cloud-server.api.mdx now includes required ResponseSamples import
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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
This PR sets up the full developer experience infrastructure for the arubacloud-api-portal open source project.
Closes #
Type of change
Changes made
cmp-catalog-apitoarubacloud-api-portalinpackage.json,package-lock.json,jest.config.tsMakefilewith targets:install,start,build,clean,gen-api-docs,clean-api-docs,regen-api-docs,pre-prREADME.mdwith badges, quick start, API coverage table, and project structureCONTRIBUTING.mdwith full development workflow, branch naming, commit conventions, PR process, and troubleshooting.github/workflows/deploy.yml— GitHub Pages deployment on push tomain.github/workflows/pr-validation.yml— build validation on every PR tomain.github/ISSUE_TEMPLATE/— bug, feature, documentation, and OpenAPI update templates.github/PULL_REQUEST_TEMPLATE.md.github/copilot-instructions.md— full AI assistant context for this projectgen-api-docs/clean-api-docsnpm scripts to pass the requiredallargumentgen-api-docs:version/clean-api-docs:versionscripts for compute v1.1docusaurus.config.jsto suppresspostman-code-generatorspath errorsOpenAPI spec changes
N/A — no spec files were modified.
Known issue
Checklist
make start)