steve/databricks-cli
steve
/
databricks-cli
mirror of https://github.com/databricks/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
databricks-cli/bundle/schema/README.md

28 lines
1.3 KiB
Markdown
Raw Normal View History

Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests
2023-03-15 02:18:51 +00:00
### Overview
`docs/bundle_descriptions.json` contains both autogenerated as well as manually written
descriptions for the json schema. Specifically
1. `resources` : almost all descriptions are autogenerated from the OpenAPI spec
Renamed `environments` to `targets` in bundle configuration (#670) ## Changes Renamed Environments to Targets in bundle.yml. The change is backward-compatible and customers can continue to use `environments` in the time being. ## Tests Added tests which checks that both `environments` and `targets` sections in bundle.yml works correctly
2023-08-17 15:22:32 +00:00
2. `targets` : almost all descriptions are copied over from root level entities (eg: `bundle`, `artifacts`)
Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests
2023-03-15 02:18:51 +00:00
3. `bundle` : manually editted
4. `include` : manually editted
5. `workspace` : manually editted
6. `artifacts` : manually editted
These descriptions are rendered in the inline documentation in an IDE
### SOP: Add schema descriptions for new fields in bundle config
1. You can autogenerate empty descriptions for the new fields by running
Rename bricks -> databricks (#389) ## Changes Rename all instances of "bricks" to "databricks". ## Tests * Confirmed the goreleaser build works, uses the correct new binary name, and produces the right archives. * Help output is confirmed to be correct. * Output of `git grep -w bricks` is minimal with a couple changes remaining for after the repository rename.
2023-05-16 16:35:39 +00:00
`databricks bundle schema --only-docs > ~/databricks/bundle/schema/docs/bundle_descriptions.json`
Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests
2023-03-15 02:18:51 +00:00
2. Manually edit bundle_descriptions.json to add your descriptions
Add top level docs for bundle json schema (#313) Co-authored-by: Pieter Noordhuis <pieter.noordhuis@databricks.com> Co-authored-by: PaulCornellDB <paul.cornell@databricks.com>
2023-04-12 19:43:53 +00:00
3. Build again to embed the new `bundle_descriptions.json` into the binary (`go build`)
Renamed `environments` to `targets` in bundle configuration (#670) ## Changes Renamed Environments to Targets in bundle.yml. The change is backward-compatible and customers can continue to use `environments` in the time being. ## Tests Added tests which checks that both `environments` and `targets` sections in bundle.yml works correctly
2023-08-17 15:22:32 +00:00
4. Again run `databricks bundle schema --only-docs > ~/databricks/bundle/schema/docs/bundle_descriptions.json` to copy over any applicable descriptions to `targets`
Add top level docs for bundle json schema (#313) Co-authored-by: Pieter Noordhuis <pieter.noordhuis@databricks.com> Co-authored-by: PaulCornellDB <paul.cornell@databricks.com>
2023-04-12 19:43:53 +00:00
5. push to repo
Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests
2023-03-15 02:18:51 +00:00
### SOP: Update descriptions in resources from a newer openapi spec
Rename bricks -> databricks (#389) ## Changes Rename all instances of "bricks" to "databricks". ## Tests * Confirmed the goreleaser build works, uses the correct new binary name, and produces the right archives. * Help output is confirmed to be correct. * Output of `git grep -w bricks` is minimal with a couple changes remaining for after the repository rename.
2023-05-16 16:35:39 +00:00
1. Run `databricks bundle schema --only-docs --openapi PATH_TO_SPEC > ~/databricks/bundle/schema/docs/bundle_descriptions.json`
Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests
2023-03-15 02:18:51 +00:00
2. push to repo